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To the Reader 


This manual is part of the BASIC documentation set. This set of manuals was designed to let you learn 
and use BASIC regardless of your prior experience with computers. The documentation set includes: 


For the beginner: 

@ Introduction to BASIC 

e BASIC for Beginners 

© More BASIC for Beginners 

For all systems: 

e BASIC User’s Guide 

@ BASIC Reference Manual 

@ BASIC Pocket Reference Guide 
For specific systems: 

e BASIC on RSTS/E Systems 

e BASIC on RSX-11M/M-—PLUS Systems 
@ BASIC on VAX/VMS Systems 


For the system manager: 


e BASIC—PLUS—2 RSTS/E Installation Guide and Release Notes 
© BASIC—PLUS—2 RSX—-11M/M-—PLUS Installation Guide and Release Notes 
@ VAX-11 BASIC Installation Guide and Release Notes 


For the beginner, Introduction to BASIC explains the fundamentals of the BASIC language and shows 
how to use BASIC to solve programming problems. BASIC for Beginners and More BASIC for 
Beginners lead the reader step-by-step through planning and writing several practical programs that 
teach BASIC programming techniques. In addition, the first chapter of the system-specific user’s guide 
tells you how to log on to your computer system, create and execute programs, and do simple file 
operations such as printing, typing, and deleting files. 
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For programmers who are more familiar with BASIC, the BASIC User’s Guide and the system-specific 
user’s guides include a complete explanation of BASIC and how to use it on your system. If you need 
information on a particular feature or statement, the BASIC Reference Manual describes the format of 
each BASIC command or keyword individually. 


The BASIC documentation set has several new features that let you find information quickly and 
easily. Each manual has its own index (with instructions on its use) and the BASIC Reference Manual 
has a master index to the entire documentation set. For quick reference the BASIC Pocket Reference 


Guide provides a brief explanation of all BASIC commands and functions. Similar information is also 
available at the computer terminal from the BASIC HELP facility. 


The following pages describe the function of this particular manual. We welcome your comments 
and encourage you to use the Reader’s Comments Form provided at the back of this book. 


Document Objectives 


This manual describes the language elements and syntax of Version 2 of VAX—11 BASIC and 
BASIC—PLUS—2. The term BASIC is used generically in this manual to refer to both VAX—11 BASIC 
and BASIC—PLUS-—2. The term VAX—11 BASIC refers specifically to VAX—11 BASIC as implemented on 
VAX/VMS systems. BASIC-PLUS-—2 refers specifically to BASIC~PLUS—2 as implemented on RSTS/E, 
RSX—11M, and RSX—11M—PLUS systems. 


Note 


For your convenience, examples, formats, or rules specific to VAX-11 BASIC, 
BASIC—PLUS—2, or BASIC—PLUS—2 on RSTS/E or RSX—11M/M-—PLUS are identified by 
a marginal symbol: 


indicates VAX—11 BASIC only. 
indicates BASIC-PLUS—2 only. 
indicates BASIC-PLUS—2 on RSTS/E systems. 


indicates BASIC—PLUS—2 on RSX—11M/M-—PLUS systems. 


intended Audience 


This manual should be used by programmers familiar with computer concepts and the BASIC lan- 
guage. It is a reference manual to be used in conjunction with the BASIC user’s guides. 


Document Structure 


This manual consists of six parts, two appendixes, and a master index to the BASIC documentation 
set. With the exception of Part |, BASIC language elements are arranged in alphabetical order within 
each part; each language element begins on a separate page. A sample format page is included on 
page xiv. 


Part | Describes BASIC program elements and structure. 


Part Il Describes BASIC compiler commands. 
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Part Il! Describes BASIC compiler directives. 


Part IV Describes BASIC statements. 
Part V Describes BASIC functions. 
Part VI Describes BASIC-PLUS—2 debugger commands. 


Appendix A Lists reserved keywords. 


Appendix B Summarizes program and subprogram coding conventions. 


This manual also includes three tabbed dividers for convenient reference: 


® The first divider summarizes the conventions used in this manual. 


@ The second divider lists most BASIC keywords by function. 


@ The third divider precedes the Master Index and describes its use. 
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Sample Format Page 


ENTRY NAME 


1.00 ENTRY NAME 


Function 


Describes the entry’s function or effect. 
Format 


A format shows the syntax of a language element. When you have a choice of formats, the 
formats are named for clarity. When a format is named General, it applies to both VAX—11 
BASIC and BASIC—PLUS—2. Format components are explained in syntax and general rules. 
When a language element has more than one format, formats are referred to by name. 
Some formats are divided into two parts. The first part, in the top portion of the box, shows 
the general elements and order of the format. 


The second part of the format, in the lower portion of the box, shows the components 
and order of the individual elements in the general format. 


Syntax Rules 


Syntax rules tell you how to order format elements to form clauses or statements. They also 
impose restrictions or relax restrictions implied by the format. 


General Rules 


General rules define the semantics of the entry and the entry’s effect on program execution or 
compilation. 


Examples 


This section presents one or more sample program lines. All examples work for both VAX—11 BASIC 
and BASIC—PLUS—2 unless otherwise noted. 
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Conventions 


Formats present the correct syntax for writing BASIC source code. You must order syntax elements as 
shown in the format unless the syntax rules indicate otherwise. 


Syntax formats consist of BASIC keywords, metalanguage mnemonics, and punctuation symbols. 
Metalanguage mnemonics are symbolic derivations of BASIC objects or structures. The tabbed 
divider that follows this section lists the most frequently used mnemonics and their meanings, as well 
as the most frequently used punctuation symbols. 


Note 


BASIC keywords are always capitalized in this manual and must be spelled exactly as 
shown. Mnemonics are in lowercase letters in formats and are italicized in the syntax 
and general rules. 


Some metalanguage mnemonics are derived directly from BASIC keywords. For example: 


® Map From MAP 
° Com From COMMON 
® Func From FUNCTION 
© Def From DEF 
@ Sub From SUB 


Others are abbreviated forms of words. For example: 


e VbI For variable 

e Unsubs For unsubscripted 
e Subs For subscripted 

@ Str For string 

© Const For constant 

® Exp For expression 

e Nam For name 

e Cond For conditional 

@ Int For integer 


e File-spec — For file-specification 


e Data-type For data-type 


Most mnemonics used in formats are combinations of mnemonics. For example: 


® Const-nam Is a constant name. 
e Sub-nam Is the name of a SUB subprogram. 
@ Unsubs-vbl Is an unsubscripted variable. (continued on next page) 


XV 


@ Int-exp Is an integer expression. 
® Cond-exp Is a conditional expression. 


@ Str-unsubs-vbl Is a string unsubscripted variable. 


Mnemonics are combined in this way to indicate exactly what type of object or structure BASIC 
expects. Some BASIC statements, for example, allow you to specify any type of variable (string or 
numeric) in the format, while others allow only a numeric variable (integer or floating-point), a string 
variable, an integer variable, or a floating-point variable. 


Thus, the uncombined form of the variable mnemonic (vb/) in a format means that you can use any 
type of variable (string or numeric). A combined variable mnemonic (such as str-vb!, num-vbl, or 
int-vbl) in a format means that you can specify only a particular type of variable. 


Within formats, mnemonics are either simple or complex. Simple mnemonics identify a format 
element (such as an expression, a variable, or a name) that needs no further definition. For example: 


EXTERNAL data-type CONSTANT const-nam.... 


The mnemonics in this format need no further definition. The EXTERNAL keyword must be followed 
by a data-type, the CONSTANT keyword, and then a const-nam. The comma and ellipsis (...), as 
defined in the Punctuation Symbols Table, indicate that you can specify more than one const-nam. 
The data-type mnemonic is defined in the Mnemonics Table as a BASIC data-type keyword, and 
const-nam is defined as a constant name. Restrictions to the use of data-type keywords in the 
EXTERNAL statement are specified in the syntax rules. 


Complex mnemonics identify a format element (such as a parameter passing mechanism or a state- 
ment clause) that has more than one component. Complex mnemonics are further defined in the 
lower portion of the format box by simple mnemonics. For example: 


Format 


Variables 

DECLARE data-type decl-item [, [ data-type ] decl-item ]... 
DEF Functions 

DECLARE data-type FUNCTION { def-nam [ ( [ def-param ].... 


Named Constants 


DECLARE data-type CONSTANT { const-nam = const }.... 


decl-item: unsubs-vbl-nam 
array-nam ( int-const,... ) 


def-param: [ data-type ] 
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When you look at the upper portion of this format, you can see that a data-type keyword must follow 
the DECLARE statement and that a decl-item must follow the data-type keyword. Dec!-item is a 
complex mnemonic that is then further defined in the lower portion of the box. There you can see 
that a decl-item can be a simple variable name or an array name followed by parentheses and integer 
constants separated by parentheses. The portion of the upper format in brackets indicates that you can 
specify another data-type keyword and another array name or simple variable name. The comma and 
ellipsis (...), as defined on the tabbed divider in this section, indicate that you can continue adding 
data-type keywords and array names or simple variable names. 


This type of format unfolds the syntax of BASIC language elements and indicates the type of element 
BASIC expects to receive. 


Note 


In most cases, BASIC signals an error if the syntax element does not exactly match the 
indicated format. In other instances, particularly with numeric elements, BASIC con- 
verts the numeric element you specify to the type of numeric element it expects to 
receive. These instances are noted in the syntax rules. 


Multiple occurrences of mnemonics in a format are numbered to prevent confusion. Vb/3, for exam- 
ple, is the third unique variable in a general format and is referred to as vb/3 in the syntax and general 
rules. 


The most frequently used punctuation symbols and metalanguage mnemonics are listed and 
described on the first tabbed divider in this manual. Less frequently used mnemonics and most 
complex mnemonics are defined as they occur in syntax formats. 


Please use the Reader’s Comments Form in the back of this book to report errors or to make sugges- 
tions for future documentation releases. 
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Conventions 


Syntax Mnemonics 


Mnemonic 


exp 
vbl 


unsubs 


subs 


array 
const 


lit 


chnl 
data-type 
file-spec 


file-nam 


Definition 


An expression 
A variable 


Unsubscripted; used with the variable mnemonic to indicate a simple variable, as opposed to an array 
element 


Subscripted; used with the variable mnemonic to indicate an array element; the element's position in the array 


is specified by subscripts enciosed in parentheses and separated by commas 
An array; syntax formats indicate whether you can specify bounds and dimensions, or just dimensions 
A constant value 


A literal value, in quotation marks; a literal is always a constant, but a constant may be named, so constants 
are not always literals 


A numeric value 

A floating-point value 
An integer value 

A character string 


Conditional; used with the expression mnemonic to indicate that an expression can be either logical or 
relational 


Logical; used with the expression mnemonic to indicate a logical expression 
Relational; used with the expression mnemonic to indicate a relational expression 
Lexical; used to indicate a component of a compiler directive 


The target point of a branch statement; used to indicate that the target point can be either a program line 
number or a statement label 


A program line number 
An alphanumeric statement label 


Allowable BASIC objects, such as variables, data types, and parameters; allowable objects are defined in 
formats as they occur 


Name; indicates the declaration of a name or the name of a BASIC structure, such as a SUB subprogram 
Specific to a COMMON 

Specific to a DEF . 

Specific to a FUNCTION subprogram 

Specific to a MAP 

Specific to a SUB subprogram 

An |/O channel associated with a file 

A data-type keyword 

A file-specification 


A file name 


Svmbols 


Definition 


(J Rrackets encinse an antinnal nartinn ata tarmat Brackets arnund vertically stacked entries indicate that vou 
can select one of the enclosed elements. You must include all punctuation as it appears in the brackets. 


{ } Braces enclose a mandatory portion of a general format. Braces around vertically stacked entries indicate 
that you must choose one of the enclosed elements. Braces also group portions of a format as a unit. You 
must include all punctuation as it appears in the braces. 


An ellipsis indicates that the immediately preceding language element can be repeated. An ellipsis following 
a format unit enclosed in brackets or braces means that you can repeat the entire unit. If repeated elements 
or format units must be separated by commas, the ellipsis is preceded by a comma (,...). 


Definitions 


In this manual, the following definitions apply: 


BASIC 


BASIC—PLUS—2 


Cannot 


Cursor 

or 
cursor position 
Must 
Program module 
Subprogram 


Subroutine 


VAX—11 BASIC 


The term BASIC refers to Version 2 of both VAX—-11 BASIC and PDP-11 
BASIC—PLUS-2. 


The term BASIC—PLUS—2 refers specifically to Version 2 of PDP-11 
BASIC-PLUS—2 as implemented on RSTS/E, RSX—11M, and RSX—11M-—PLUS 
systems. 


Cannot indicates than an operation cannot be performed and that an attempt to 
perform the operation causes BASIC to signal an error. 


Cursor or cursor position refers to a terminal’s print mechanism. It can be the 
flashing Cursor on a video display terminal or the print head on a hard-copy 
terminal. 


Must indicates that an operation must be performed and that failure to perform the 
specified operation causes BASIC to signal an error. 


A program module is a BASIC main program, a SUB subprogram, or a FUNCTION 
subprogram. 


A separately compiled program module that must be linked or task-built with the 
main program. 


A subroutine is a block of code accessed by a GOSUB or ON GOSUB statement. It 
is always in the same program module as the statement that accesses it. 


The term VAX—-11 BASIC refers specifically to Version 2 of VAX-11 BASIC as 
implemented on VAX/VMS systems. 


Functional List of BASIC Keywords 


Arrays 


DET 
DIMENSION 
MAT 

MAT INPUT 
MAT LINPUT 
MAT PRINT 
MAT READ 
NUM 

NUM2 


rPraas 


Data Conversion 


ASCII 
CHANGE 
CHR$ 
NUM$ 
NUM1$ 
STR$ 

~ VAL 
VAL% 


Data Definition 


COMMON 
DECLARE 
DIMENSION 
MAP 


MAP DYNAMIC 


MOVE 
RECORD 
REMAP 


Data Formatting 


FORMAT$ 
PRINT USING 


Data Typing 


COMMON 
DECLARE 
DEF 
DIMENSION 
EXTERNAL 
FUNCTION 
MAP 
OPTION 
SUB 


Date and Time Conversion 


DATE$ 
TIME 
TIMES 


Error Handling 
ERL 
ERN$ 
ERR 


ERT$ 


ON ERROR GO BACK 
ON ERROR GOTO 
ON ERROR GOTO 0 


RESUME 


Function Definition 


DEF 
END DEF 


END FUNCTION 


EXIT DEF 


EXIT FUNCTION 


EXTERNAL 
FUNCTION 


1/0 to Files 


CLOSE 
DELETE 
FIND 

FREE 

GET 
INPUT # 
INPUT LINE # 
KILL 
LINPUT # 
MAR 
MARGIN 
MOVE 
NAME AS 
OPEN 
PRINT # 
PUT # 
RECOUNT 
RESTORE # 
SCRATCH 
UNLOCK 
UPDATE 


I/O to Terminals 


CCPOS 
CTRLC 
ECHO 
INPUT 
INPUT LINE 
LINPUT 
MAR 


NOECHO 
PRINT USING 
RCTRLC 
RCTRLO 
RECOUNT 
TAB 


Numbers 


ABS 
ATN 
COMP% 
COS 
DECIMAL 
EXP 

FIX 

INT 
INTEGER 
LOG 
LOG10 
MAG 
RANDOMIZE 
REAL 
RND 
SGN 

SIN 

SQR 
SWAP% 
TAN 


Program Control 


END 

EXIT LOOP 
FOR 
GOSUB 
GOTO 

IF 

ITERATE 
ON GOTO 
RETURN 
SELECT 
SLEEP 
STOP 
UNLESS 
UNTIL 
WAIT 
WHILE 


Program Segmentation 


CALL 
CHAIN 


END FUNCTION 


END SUB _ 


EXIT FUNCTION 


EXIT SUB 
EXTERNAL 
FUNCTION 
LOC 

SUB 


Strings 


EDIT$ 
FORMAT$ 
INSTR 
LEFT$ 
LEN 

LSET 
MID$ 
POS 
RIGHT$ 
RSET 
SEG$ 
SPACE$ 
STRING$ 
TRM$ 
XLATE 


String Arithmetic 


DIF$ 
PLACE$ 
PROD$ 
QUO$ 
SUM$ 


Value Assignmen 


DATA 
LET 

LSET 
READ 
RESTORE 
RSET 


PART | 
Program Elements 
and Structure 


1.0 Elements of a BASIC Program 


A BASIC program is a series of program lines that contain instructions for the BASIC compiler. These 
instructions are in the form of BASIC statements. Program lines contain the BASIC keywords, opera- 
tors, and operands that make up a BASIC program. 


The first line of a BASIC program must begin with a line number. The program lines that follow may 
contain: 


¢ Line numbers or labels 

e Statements 

e Optional compiler directives 
© Optional comment fields 


e Line terminator (carriage return) 


1.1 Line Numbers 


Every BASIC statement must be associated with a line number. Thus, the first element in a BASIC 
program must be a line number. A line number must be an integer between 1 and 32767, inclusive. 
A space or tab terminates the line number. Embedded spaces, tabs, and commas within line numbers 
are invalid. 


A line number followed by a carriage return does not constitute a BASIC program line. A program line 
must contain a statement or a comment field. Comment fields are discussed in Section 2.1. A new 
line number or a Carriage return terminates a BASIC program line. 


A program line can contain any number of text lines; however, a text line cannot exceed 255 


characters in VAX-11 BASIC and BASIC-PLUS—2 on RSTS/E systems, and 132 characters in 
BASIC—PLUS—2 on RSX—11M/M-—PLUS systems. 
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The BASIC language uses line numbers to: 
e Indicate the order of statement execution 
e Provide control points for branching 

e Help in debugging and updating programs 
e Find the location of run-time errors 


e Resume processing after an error has been handled 


Therefore, each line number must be unique. BASIC ignores leading spaces, tabs, and zeros in line 
numbers. 


1.2 Labels 


A label is a 1— to 31—-character name that immediately precedes a statement. It may immediately 
follow a line number. The label logically identifies a statement or block of statements. The label name 
must conform to the rules for naming variables, described in Section 6.1. The label name must be 
separated from the statement it labels with a colon (:). For example: 


100 Yes routine: PRINT "Your answer is YES," 


The colon is not part of the label name. It tells BASIC that the label is being defined rather than 
referenced. Consequently, the colon is not allowed when you use a label to reference a statement. 
For example: 


200 GOTO Yes_routine 


The BASIC language uses labels to: 
e Provide contro! points for branching 


e Help in debugging programs 


e Help in maintaining and updating programs 
You can reference a label anywhere you can reference a line number, with three exceptions: 


e You cannot compare the value returned by the ERL function (the line number associated with the 
program line where the last error occurred) with a label. 


e You cannot use the RESUME statement to reference a label. 


e You cannot reference a label in an IF-THEN-—ELSE statement without using the keyword GOTO or 
GO TO. You can use the implied GOTO form only to reference a line number. For example: 


100 IF AZ = Bt 
THEN 1000 
ELSE 1050 

200 IF A$ = "YES" 


THEN GOTO Yes 
ELSE GOTO No 
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Because the first statement references a line number, the GOTO keyword is not required; the second 
statement references a label, so the GOTO keyword is required. 


1.3 Statements 


A BASIC statement consists of a statement keyword and optional operators and operands. For 
example: 


400 LET AX = 534% + (SUMZ - DIF) 
PRINT A% 


The first statement assigns a value to the integer variable A%. The PRINT statement causes BASIC to 
display the value of A% on your terminal. 


A statement is either executable or nonexecutabie: 


e Executable statements perform operations (for example, PRINT, GOTO, and READ). 


e Nonexecutable statements describe the characteristics and arrangement of data, specify usage infor- 
mation, and serve as comments in the source program (for example, DATA, DECLARE, and REM). 


BASIC can accept and process one statement on a line of text, several statements on a line of text, 
multiple statements on multiple lines of text, and single statements continued over several lines of 
text. Each line of program text is associated with the last specified line number. 


Multi-statement and continuation lines are discussed in Sections 1.3.2 and 1.3.3. 


1.3.1 Keywords 


A keyword is a reserved element of the BASIC language. Every statement except LET and empty 
statements must begin with a keyword. BASIC uses keywords to: 


e Define data and user identifiers 
e Perform operations 
e Invoke built-in functions 


Note 


Keywords are reserved words and cannot be used as variable names or as names for 
MAP or COMMON areas. 


Keywords cannot be used in any context other than as BASIC keywords. STRING$ = ‘YES’, for 
example, is invalid because STRING$ is a reserved BASIC keyword. Appendix A in this manual 
contains a list of BASIC reserved keywords. 


A BASIC keyword cannot have embedded spaces and cannot be split across lines of text. There must 
be a space, tab, or special character such as a comma between the keyword and any other variable or 
operator. 
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Some keywords use two words. In this case, their spacing requirements vary, as shown in Table 1. 


Table 1: Keyword Space Requirements 


Optional Space | Mandatory Space No Space 


GO SUB BY DESC FNEND 
GO TO BY REF FNEXIT 
ON ERROR | BY VALUE FUNCTIONEND 
END DEF FUNCTIONEXIT 
END FUNCTION }| NOECHO 
END GROUP NOMARGIN 
END IF SUBEND 
END RECORD SUBEXIT 
END SELECT 
END SUB 
EXIT DEF 
EXIT FUNCTION 
EXIT SUB 
INPUT LINE 
MAP DYNAMIC 
MAT INPUT 
MAT LINPUT 
MAT PRINT 
MAT READ 


1.3.2 Single-Statement Lines and Continued Statements 


A single-statement line consists of one statement on one numbered line or one statement continued 
over two or more text lines. For example: 


100 PRINT B * C / 12 


This single-statement line has a line number, keyword (PRINT), operators (*, /), and operands (B, C, 
and 12). . 


You can have a single statement span several text lines by typing an ampersand (&) and a carriage 
return. For example: 


100 OPEN "SAMPLE.DAT" AS FILE 2% &RED 
SEQUENTIAL VARIABLE: &ED 
MAP ABC 


The ampersand must come immediately before the carriage return in VAX—11 BASIC. BASIC—PLUS—2 
ignores spaces or tabs that follow the ampersand and precede the carriage return. For compatibility, 
DIGITAL recommends that you type the carriage return immediately after the ampersand. 


The ampersand continuation character may be used but is not required for continued REM state- 
ments. The following example is valid: 


100 REM This is a remark 
And this is also a remark 
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You can continue any BASIC statement, but you cannot continue a string literal or BASIC keyword. 
For example, BASIC returns the error message ‘‘Unterminated string literal’ if you try to print the 
following: 


100 PRINT "FEE-FIE- 
FOE-FUM" 


tad 


This example is valid: 


200 PRINT "FEE-"5 & 
"FIE-"§ & 
"FOE-"3§ & 
"PUM u 


A more efficient way to continue string literals is to use the string concatenation operator: 


100 PRINT "FEE-" & 
+ "FIE-" a 
+ "FOE-" é 
+ "PUM" 


BASIC concatenates the four string literals at compile time and stores them as one string. When the 
PRINT statement executes, BASIC displays the one concatenated string literal rather than four sepa- 
rate string literals, thereby causing your program to execute faster and more efficiently. 


Continued statements do not have line numbers, although the compiler counts and numbers them as 
sublines. 


1.3.3 Multi-Statement Lines 


Multi-statement lines contain several statements on one line of text or multiple statements on separate 
lines of text. All the statements on a multi-statement line are associated with a single line number. 


Multiple statements on one line of text must be separated by backslashes (\). For example: 


400 PRINT A \ PRINT VY \ PRINT G 


Because all statements are on the same program line, any reference to line number 400 refers to all 
three statements and execution begins with the first statement on the line. That is, BASIC cannot 
execute the second statement without executing the first statement. 


A statement that unconditionally transfers control to another program line should always be the last 
statement on a multi-statement line. Otherwise, the statements that follow the statement transferring 


control will never execute. The following program line, for example, will execute, but it is not 
recommended: 


200 PRINT A \ GOTO 410 \ PRINT B 


BASIC prints the value of A and then branches to line 410. The statement PRINT B will never execute. 


BASIC Reference Manual 5 


You can also write a multi-statement program line that associates all statements with a single line 
number by ending each statement with an ampersand (&) and a carriage return and preceding the 
next statement with a backslash. For example: 


400 PRINT A & 
\ PRINT Vo & 
\ PRINT G 


Because programs written in this format tend to be cluttered and hard to read, BASIC allows you to 
associate multiple statements with a line number by placing each statement on a separate line without 
using the ampersand or backslash. This format requires only a space or tab at the beginning of each 
new line of text. BASIC assumes that such an unnumbered line of text is either a new statement or an 
IF statement clause. For example: 


400 PRINT A 
PRINT B 
PRINT "FINISHED" 


In this example, each line of text begins with a BASIC statement and each statement is associated with 
line number 400. 


BASIC also recognizes IF statement keywords on a new line of text and associates such keywords with 
the preceding IF statement. For example: 


100 IF (A$ = "YES") OR (AS = "¥") 
THEN PRINT “You typed YES" 
ELSE PRINT "You typed NO" 
STOP 
END IF 


The BASIC compiler listing file numbers the lines associated with line number 100 as they occur. The 
VAX—11 BASIC listing file looks like this: 


1 109 IF (A$ = "YES") OR (AS = "¥") 
2 THEN PRINT "You typed YES" 

3 ELSE PRINT "You typed NO" 

4 STOP 

+) END IF 


The BASIC—PLUS-—2 listing file looks like this: 


ooo001 100 IF (AS = "YES") OR (AS = "Y¥") 
00002 THEN PRINT "You typed YES" 
00003 ELSE PRINT "You typed NO" 
00004 STOP 

00005 END IF 


Each statement has a number that indicates its position in the line. The BASIC compiler counts the 
statements in a multi-statement line to locate compile-time errors. You cannot use statement numbers 
as targets of branch statements. Targets of branch statements such as GOTO must be a line number or 
a label. 
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You can use any BASIC statement in a multi-statement line. However, a REM or DATA statement 
must be the last statement on a multi-statement line. This is because the compiler: 


e lgnores all text following a REM keyword until it reaches a new line number. 


DATA statement in your program has to have its own line number. 


Because a leading space or tab not followed by a line number implies a new statement in a multi- 
statement line, compiler commands and immediate mode statements cannot be preceded by a space 
or tab. If you enter a compiler command or immediate mode statement, you cannot add more 
continuation lines to the last program line. If you attempt to do so, BASIC signals the error “unknown 
command input’. 


1.4 Compiler Directives 


Compiler directives are instructions in a program that tell BASIC to perform certain operations as it 
compiles the program. With compiler directives, you can: 


e Place program titles and subtitles in the header that appears on each page of the listing file 
e Place a program version identification string in both the listing file and object module 

e Start or stop the accumulation of listing information for selected parts of a program 

© Start or stop the accumulation of cross-reference information for selected parts of a program 
e Include BASIC code from another source file 

© Conditionally compile parts of a program 

e Terminate compilation 


e Include CDD record definitions in a BASIC program (VAX—11 BASIC only) 
All compiler directives: 


e Must begin with a percent sign 

e Can be preceded by an optional line number 

¢ Must be the only text on the line (except for %IF-% THEN—%ELSE—-%END—%IF) 
e Must be preceded by a space, tab, or line number 


e Cannot appear within a quoted string 


See the BASIC User’s Guide and Part III in this manual for more information on compiler directives. 


1.5 Line Terminators 


In the BASIC environment, a carriage return/line feed combination (RED) followed by an optional 
space or tab and a new line number ends a BASIC program line. An ampersand followed by a 
carriage return ends a line of text but not the program line. All statements between the first line 
number and the next line number are associated with the first line number. 
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1.6 Lexical Order 


Lexical order refers to the order in which BASIC compiles statements in a program. In general terms, 
BASIC compiles program lines in sequential order from the lowest to the highest line number. Thus, 
statement A precedes statement B if the line number with which statement A is associated is lower 
than the line number with which statement B is associated. If both statements are associated with the 
same line number, statement A precedes statement B only if it physically precedes statement B or 
appears to the left of statement B. BASIC processes statements on a line of text from left to right and 
lines of text from top to bottom. 


Some BASIC statements, such as comments and MAP declarations, are nonexecutable. If program 
control passes to a nonexecutable statement, BASIC executes the first statement that lexically follows 
the nonexecutable statement. 


2.0 Program Documentation 


Documentation clarifies and explains source program structure. You can provide such explanations 
with: 


¢ Comment fields 


e REM statements 


2.1 Comment Fields 


A comment field begins with an exclamation point (!) and ends with a carriage return. You supply text 
after the exclamation point to document your program. BASIC does not execute text in a comment 
field. For example: 


100 ! FOR loop to initialize list 9 
FOR I = i TO 10 
QO(I) = O ! This is a comment 
NEXT I 


! List now initialized 
BASIC executes only the FOR loop. The comment fields, preceded by exclamation points, do not 
execute. 


Comment fields help make your program more readable and allow you to format your program into 
readily visible logical blocks. They can also serve as target lines for GOTO and GOSUB statements: 


10 i 
! Square root Program 
I 
INPUT ‘Enter a number’ 5A 
PRINT ‘SQR of ‘’SAS’is ‘350R(A) 
! 
! More suare roots? 
! 
INPUT ‘Type "¥" to continues a carriagye return to auit’ sANSS 
GOTG 10 IF ANS# = ‘¥? 
| 
99 END 
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You can also use an exclamation point to terminate a comment field, but this practice is not recom- 
mended. Therefore, you should make sure that there are no exclamation points in the comment field 
itself; otherwise, BASIC treats the text remaining on the line as source code. 


Note 


Comment fields in DATA statements are invalid; the compiler treats the comments as 
additional data. 


2.2 REM Statements 


A REM statement begins with the REM keyword and ends when BASIC encounters a new line 
number. The text you supply between the REM keyword and the next jine number documents your 
program. Like comment fields, REM statements do not affect program execution. BASIC ignores all 
characters between the keyword REM and the next line number. Therefore, the REM statement can be 
continued without the ampersand continuation character and should be the only statement on the 
line or the last of several statements in a multi-statement line: 


10 REM This is an example 
20 A=5 
B=10 


REM A esuals 5 
B equals 10 
30 PRINT A; B 


The REM statement is nonexecutable. When you transfer control to the line number of a REM 
statement, BASIC executes the next executable statement that lexically follows the referenced line. 
For example: 


fmt ta Yr * 
id REM #* Ssuare root Frogram 
é 


20 INPUT ‘Enter a number’3A 
PRINT ‘SOR of ‘Ai ’is “’3SOR(A} 
INPUT ‘Tyre "¥" to continues a carriage return to auit’ sANS# 
GOTO i0 IF ANSS = “¥? 

40 END 


When the conditional GOTO statement in line 20 transfers program control to line 10, BASIC ignores 
the REM comment on line 10 and continues program execution at line 20. 


Note 


Because BASIC treats all text between the REM statement and the next line number as 
commentary, REM should be used very carefully in programs that follow the implied 
continuation rules. Program statements intended for execution will not execute when 
they are inside a REM statement. DIGITAL recommends the use of comment fields (!) 
for program documentation in programs formatted with implied continuation lines. 
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2.3 Empty Statements 


Empty statements consist of a line number and an exclamation mark followed by optional text, a line 
terminator and a new line number. For example: 


100 { 
! FOR loorp to initialize list 9 
1 


200 FOR I = 1 TO 10 
QO(I) = 0 ! This is a comment 
NEXT I 
300 ! 
| List is now initialized 


Lines 100 and 300 are empty statements. 


3.0 BASIC Character Set 

BASIC uses the full ASCII character set. This includes: 
@ The letters A through Z, both upper- and lowercase 
® The digits 0 through 9 


e Special characters 


Appendix C in BASIC on VAX/VMS Systems, BASIC on RSX-11M/M-—PLUS Systems, and BASIC on 
RSTS/E Systems contains the full ASCII character set and character values. 


The compiler: 


e Does not distinguish between upper- and lowercase letters except in string literals or within aa DATA 
statement 


¢ Does not process nonprinting characters unless they are part of a string literal 


e Does not process characters in REM statements or comment fields 
In string literals, BASIC processes: 


e Lowercase letters as lowercase 


e Nonprinting characters 


The ASCII character NUL (ASCII code 0) and line terminators cannot appear in a string literal. Use the 
CHR$ function or explicit literal notation to use this character and terminators. 


You can use nonprinting characters in your program, for example, in string constants, but to do so 
you must use: 1) a predefined constant such as ESC and DEL, 2) the CHR$ function to specify an 
ASCII value, or 3) explicit literal notation for character constants. See Section 5.4 in this manual for 
more information on explicit literal notation. See the BASIC User’s Guide for more information on 
predefined constants and the CHR$ function. 


4.0 BASIC Data Types 


All data in a BASIC program has a specific data type that determines how many bits of storage should 
be considered as a unit and how the unit is to be interpreted and manipulated. 
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VAX-11 BASIC recognizes five primary data types: integer, floating-point, character string, packed 
decimal, and RFA. These types correspond to the BASIC generic data-type keywords: 


e INTEGER 
e REAL 

e STRING 
¢ DECIMAL 
e RFA 


BASIC—PLUS—2 recognizes four primary data types: integer, floating-point, character string, and RFA. 
These types correspond to the BASIC generic data-type keywords: 


e INTEGER 
e REAL 

e STRING 
e RFA 


Integer data are stored as binary values in a byte, a word, or a longword. These values correspond to 
the BASIC data-type keywords: 


e BYTE 
e WORD 
e LONG 


Floating-point values are stored using a signed exponent and a binary fraction. VAX—11 BASIC allows 
four floating-point formats: single, double, gfloat, and hfloat. These formats correspond to the BASIC 
data-type keywords: 


e SINGLE 


¢ DOUBLE 
e GFLOAT 
e HFLOAT 


BASIC—PLUS—2 allows only single and double floating-point formats. These formats correspond to the 
BASIC data-type keywords: 


e SINGLE 
e DOUBLE 


VAX—11 BASIC packed decimal data is stored in a string of bytes. Refer to Appendix C in BASIC on 
VAX/VMS Systems for more information on the storage of packed decimal data. 


Character data are strings of bytes containing ASCII codes as binary data. The first character in the 
string is stored in the first byte, the second character is stored in the second byte, and so on. VAX—11 
BASIC allows up to 65535 characters for a STRING data element. BASIC—PLUS—2 allows up to 32767 
characters. 
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In addition to these data types, BASIC also recognizes a special RFA data type to provide information 
about a Record File Address (RFA). A Record File Address consists of a block number within a file and 
an offset into that block. An RFA uniquely identifies a record in a file. You can access RMS files of any 
organization by Record File Address (RFA). This means that you specify the disk address of a record, 
and RMS retrieves the record at that address. Accessing records by RFA is more efficient and faster 
than other forms of random record access. 


The RFA data type is unique and can be used only for: 
e RFA operations (with the GETRFA function and GET and FIND statements) 
e Assignments to other variables of the RFA data type 


¢ Comparisons with other variables of the RFA data type using the equal to (=) or not equal to (<>) 
relational operators 


e Formal and actual parameters 


e DEF and function results 


You cannot use variables or constants of the RFA data type for any arithmetic operations. You cannot 
declare a constant of the RFA data type. 


The RFA data type requires six bytes of information: four bytes for the address of a disk block, and 
two bytes for the offset into the disk block. See Chapter 9 in the BASIC User’s Guide for more 
information on Record File Addresses and the RFA data type. 

Table 2 lists BASIC data-type keywords and summarizes BASIC data types. 


Table 2: BASIC Data Types 


Precision 
Data Type (decimal 
Keyword* Range** digits) 


INTEGER — specifies integer data 
BYTE 8 bits —128 to +127 
WORD 16 bits —32768 to + 32767 


LONG 32 bits ~2147483648 to 
+ 2147483647 


REAL — specifies floating-point data 
SINGLE 32 bits 29 * 10° to 1.7 * 10° 
DOUBLE 64 bits 29 * 10°” to 1.7 * 10” 
GFLOAT 64 bits 56* 10°” to .9* 10 
HFLOAT 128 bits 84* 10°” to .59 * 10°” 
DECIMAL(d,s) Oto 16 bytes 1+*10°' to1+* 10" 


STRING One character 
per byte 


RFA 6 bytes 


* VAX-11 BASIC only data types are italicized. 


*™* Approximate for REAL and DECIMAL data types. 
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For the VAX—17 BASIC only DECIMAL data type, you can specify the total number of digits (d) in the 
data type and the number of digits to the right of the decimal point (s). For instance, DECIMAL(10,3) 
specifies decimal data with a total of 10 digits, 3 of which are to the right of the decimal point. 


In Table 2, REAL and INTEGER are generic data-type keywords that specify floating-point and integer 
(SINGLE, DOUBLE, GFLOAT or HFLOAT in VAX—11 BASIC, BYTE, WORD, or LONG) depends 
on the current default. That is, if you do not explicitly type REAL and INTEGER data as SINGLE, 
DOUBLE, BYTE, WORD, and so on, BASIC uses the current defaults for REAL and INTEGER. 


You can specify data-type defaults in the BASIC environment with the SET and COMPILE commands 
or in a program module with the OPTION statement. On VAX/VMS systems, you can also specify 
data-type defaults from DCL level with the DCL BASIC command. You can also specify whether 
program values are to be typed implicitly or explicitly. The following sections discuss data-type 
defaults and implicit and explicit data typing. 


4.1 Implicit Data Typing 


You implicitly assign a data format to program values by adding a suffix to the variable name or 
constant value or by specifying no suffix with the variable name or constant value: 


e A dollar sign suffix ($) specifies STRING storage. 
e A percent sign suffix (%) specifies INTEGER storage. 


e No suffix character specifies storage of the default type, which may be INTEGER, REAL, or 
DECIMAL (VAX—11 BASIC only). 


Suffixes on variable names and program constants specify string, integer, or floating-point storage of 
the default size. No suffix character implies that the value is of the default type (integer, floating- 
point, or packed decimal in VAX—11 BASIC). With implicit data typing, the range and precision for 
integer, floating-point, and packed decimal values (VAX—11 BASIC only) is determined by the current 
default data type. The default data type is determined by the system default (REAL) or the data type set 
for the BASIC environment with the SET or COMPILE commands. VAX—77 BASIC qualifiers are 


described in Table 16. BASIC—PLUS-—2 qualifiers are described in Table 17. 


Note that if you compile your program with the /TYPE: EXPLICIT qualifier, you cannot type program 
values implicitly. All program values must be explicitly assigned a data type in your program or 
BASIC signals an error. 


Good programming practice dictates that you do not mix implicit and explicit data typing in expres- 
sions or in program units and that you do not rely extensively on implicit data typing. Explicit data 
typing makes programs easier to understand and maintain because the data type of all program values 
is explicitly spelled out in the program and is not as dependent upon compilation defaults that may 
change. 


4.2 Explicit Data Typing 


Explicit data typing means that you use a declarative statement to specify the type, range and preci- 
sion of your program values. Declarative statements associate attributes such as data type and value 
with user identifiers. For example: 
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100 DECLARE STRING CONSTANT ZIP.CODE = 03060 
DECLARE STRING EMP_NAME;+; DOUBLE WITH. TAX, SINGLE INT_RATE 


The first DECLARE statement associates the constant value 03060 and the STRING data type with a 
constant named ZIP_CODE. The second DECLARE statement associates the STRING data type with 
EMP_NAME, the DOUBLE data type with WITH_TAX, and the SINGLE data type with INT_RATE. 
No constant values are associated with user identifiers in the second DECLARE statement because 
they are variable names. | 


With explicit data typing, each program variable within a program can have a different range and 
precision. This gives you more control over your program. Because you can explicitly assign data 
types to variables, constants, arrays, parameters, and functions, all integer data, for instance, does not 
have to take the compilation defaults. Likewise, all floating-point data does not have to take the 
compilation default because you can declare floating-point values as SINGLE or DOUBLE in 
BASIC—PLUS—2 and as SINGLE, DOUBLE, GFLOAT, or HFLOAT in VAX—11 BASIC. See the BASIC 
User’s Guide and the sections on these statements in this manual for more information on explicitly 
typing data. 


Using the REAL and INTEGER keywords to explicitly type program values allows you to write pro- 
grams that are transportable across systems, since these data-type keywords specify that all floating- 
point and integer data take the current default for REAL and INTEGER. The data type INTEGER, for 
example, specifies only that the constant or variable is an integer. The actual subtype (BYTE, WORD, 
or LONG) depends on the default set with the COMPILE or SET command, the VAX—11 BASIC DCL 
BASIC command, or the OPTION statement. 


You can also specify a particular data type size for values declared INTEGER or REAL with compila- 
tion qualifiers. The qualifier /DOUBLE, for instance, specifies that all data typed REAL is to be treated 
as double-precision data. 


The /TYPE: EXPLICIT qualifier or OPTION TYPE= EXPLICIT statement allows you to specify that all 
program data must be explicitly typed. Compiling a program with /TYPE: EXPLICIT or specifying 
OPTION TYPE=EXPLICIT means that any program value not explicitly declared causes BASIC to 
signal an error. 


For new applications, DIGITAL recommends using BASIC’s explicit data typing features. See Chapter 
5 of the BASIC User’s Guide for more information. 


5.0. Constants 


A constant is a numeric or character literal that does not change during program execution. A 
constant can also be named and associated with a data type. BASIC allows the following types of 
constants: 


e Numeric 
Floating-point 
Integer 
Packed decimal (VAX—11 BASIC only) 


e String (ASCII characters enclosed in quotation marks) 
A constant of any of the above data types can be named with the DECLARE CONSTANT statement. 


You can then refer to the constant by name in your program. Refer to Section 5.3 for information on 
naming constants. 
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You can also use a special explicit literal notation to specify the value and data type of a numeric 
literal. Explicit literal notation is discussed in Section 5.4. 


If you do not specify a data type for a numeric constant with the DECLARE CONSTANT statement or 
with explicit literal notation, the type and size of the constant is determined by the default REAL, 
INTEGER, or (VAX—17 BASIC only) DECIMAL set: 


e At installation (BASIC—PLUS—2 only) 

e With the DCL BASIC command (VAX—11 BASIC only) 
e With the SET command 

e With the COMPILE command 

e With the OPTION statement 


BASIC also supplies predefined constants for ease in representing some ASCII characters and mathe- 
matical values. 


The following sections discuss numeric and string constants, named constants, explicit literal nota- 
tion, and predefined constants. 


5.1 Numeric Constants 


A numeric constant is a literal or named constant whose value never changes. In VAX—11 BASIC, a 
numeric constant can be a floating-point number, an integer, or a packed decimal number. In 
BASIC—PLUS—2, a numeric constant can be either a floating-point number or an integer. The type and 
size of numeric constants are determined by the current default values, the data-type qualifiers 
specified with the COMPILE command, the defaults set by the SET command, the data type specified 
in a DECLARE CONSTANT or OPTION statement, or by explicit literal notation. 


If you use a declarative statement to declare data type and name a numeric constant, the constant is 
of the type and size specified in the statement. For example: 


100 DECLARE BYTE CONSTANT AGE = 12 


This example associates the numeric literal 12 and the BYTE data type with the user identifier AGE. 
To specify a data type for unnamed numeric constants, you must use the explicit literal notation 
format described in Section 5.4. 


5.1.1 Floating-Point Constants 


A floating-point constant is a literal or named constant with one or more decimal digits, either 
positive or negative, an optional decimal point and an optional exponent (E notation). If the default 
data type is INTEGER, a decimal point or an E is required or BASIC treats the literal as an INTEGER. In 
VAX—-11 BASIC, if the default data type is DECIMAL, an E is required or VAX—11 BASIC treats the 
literal as a packed decimal value. The following, for example, are REAL literals: 


Default type REAL: 


—8.738 
239.21E-6 
ee) 

299 
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Default type INTEGER: 


—8.738 
239.21E—-6 


PY fe 
299E 


Default type DECIMAL (VAX-11 BASIC only): 


—8.738E 
239.21E—6 


79E 
299E 


Very large and very small numbers can be represented in E (exponential) notation. This form of 
mathematical shorthand uses the format: 


+ number E + n 


where: 


+ or- 


number 


+ or- 


Is the number’s sign. The plus sign is optional, but negative numbers require a minus 
sign. 


Is the number carried to a maximum of: 

e 6 decimal places for SINGLE precision 

e 16 decimal places for DOUBLE precision 

e 15 decimal places for GFLOAT precision (VAX—11 BASIC only) 
e 33 decimal places for HFLOAT precision (VAX—71 BASIC only) 


Represents the words ‘‘times 10 to the power of.’’ 


Is the exponent’s sign. The plus sign is optional, but the minus sign is mandatory for 
negative exponents. 


Is an integer constant (the power of 10). If an exponent sign is specified, n can be zero, 
but not blank. If an exponent sign is not specified, n can be blank. 


Table 3 compares numbers in standard and E notation. 


Table 3: Numbers in E notation 


.0000001 
1,000,000 


Standard Notation | Notation 


—10,000,000 
100,000,000 
1,000,000,000,000 
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The range and precision of floating-point constants are determined by the current default data types or 
the explicit data type used in the DECLARE CONSTANT statement. There are, though, limits to the 
range allowed for numeric data types. Table 2 lists BASIC data types and ranges. BASIC signals the 
fatal error ‘floating point error or overflow’’ when your program specifies a constant value outside of 


tha allawahla ranga far a flaatin 
ul oa owt Ce FaNveceuiis 


g-naint data ty 
BIN CAG VY Cerri UT @ bed MJT .S 


oO v Mae ype. 


5.1.2 Integer Constants 


An integer constant is a literal or named constant, either positive or negative, with no fractional digits 
and an optional trailing percent sign (%). The percent sign is required for integer literals if the default 
type is not INTEGER. For example: 


Default type INTEGER: 


81257 
—3477 
79 


Default type REAL or (VAX—17 BASIC only) DECIMAL: 


81257% 
—3477% 
79% 


The range of allowable values for integer constants is determined by either the current default data 
type or the explicit data type used in the DECLARE CONSTANT statement. Table 2 lists BASIC data 
types and ranges. BASIC signals an error for a number outside the applicable range. 


BASIC treats numeric literals as floating-point numbers unless: 
e The default data type is INTEGER 
e The literal has a % suffix 


Thus, BASIC must convert numeric literals when assigning them to integer variables. This means that 
your program runs somewhat slower than it would if integer values were explicitly declared. You can 
prevent this conversion step by using percent signs for integer constants, numeric literal notation, or 
named integer constants. 


Note 


You cannot use percent signs in integer constants that appear in DATA statements. An 
attempt to do so causes BASIC to signal ‘‘Data format error’ (ERR=50). 


5.1.3 Packed Decimal Constants (VAX-—11 BASIC Only) 


A packed decimal constant is a number, either positive or negative, that has a specified number of 
digits and a specified decimal point position (scale). You specify the number of digits (d) and the 
position of the decimal point (s) when you declare the constant as a DECIMAL. If the constant is not 
declared, the number of digits and the position of the decimal are determined by the representation of 
the constant. For example, when the default data type is DECIMAL, 1.234 is a DECIMAL(4,3) con- 
stant, regardless of the default decimal size. Likewise, using explicit literal notation, ‘1.234’’P is a 
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DECIMAL(4,3) constant, regardless of the default data type and default DECIMAL size. Explicit literal 
notation is described in Section 5.4. See the BASIC User’s Guide for more information on packed 
decimal numbers. 


5.2 String Constants 


String constants are either string literals or named constants. A string literal is a series of characters 
enclosed in string delimiters. Valid string delimiters are: 


e Double quotation marks (‘‘text’’) 


e Single quotation marks (‘text’) 


You can embed double quotation marks within single quotation marks (‘this is a ‘‘text’’ string’) and 
vice versa (“this is a ‘text’ string’). Note, however, that BASIC does not accept incorrectly paired 
quotation marks and that only the outer quotation marks must be paired. The following character 
strings, for example, are valid: 


“The record number does not exist.’’ 
“I’m here!”’ 
“The terminating ‘condition’ is equal to A$.” 
“REPORT 543” 
The following strings are not valid: 
“Quotation marks do not match’ 
“No closing quotation mark 


Characters in string constants can be letters, numbers, spaces, tabs, or any ASCII character except a 
line terminator or NUL (ASCII code 0). If you need a string constant that contains a NUL, you should 


use the NUL predefined constant in a compile-time constant expression or explicit literal notation. 
See Section 5.4 in this manual for information on explicit literal notation and the BASIC User’s Guide 
for more information on the NUL predefined constant. 


BASIC determines the value of the string constant by scanning all its characters. For example, because 
of the number of spaces between the delimiters and the characters, these two string constants are not 
the same: 


= END-—OF-FILE REACHED” 
“END—OF-FILE REACHED” 


BASIC stores every character between delimiters exactly as you type it into the source program, 
including: 


e Lowercase letters (a—z) 
e Leading, trailing, and embedded spaces 
© Tabs 


e Special characters 
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BASIC does not print the delimiting quotation marks when executing the program. That is, the value 
of the string constant does not include the delimiting quotation marks. For example: 


100 PRINT "END-OF-FILE REACHED" 


RUNNH 
END-OF-FILE REACHED 


BASIC prints double or single quotation marks when they are enclosed in a second paired set: 


100 PRINT ‘FAILURE CONDITION: “RECORD LENGTH"’ 
! 
! 

200 END 

RUNNH 


FAILURE CONDITION: "RECORD LENGTH" 


5.3 Named Constants 


BASIC allows you to name constants. You can assign a mnemonic name to a constant that is internal 
to your program and refer to the constant by name throughout the program. You can also name a 
constant that is external to your program and refer to it by name throughout your program. This 
naming feature is useful for the following reasons: 


e lf a commonly-used constant must be changed, you need to make only one change in your 
program. 


e A logically named constant makes your program easier to understand. 


You can use named constants anywhere you can use a constant, for example, to specify the number 
of elements in an array. 


You cannot change the value of an explicitly named constant during program execution. To change 
the value of a constant, you must change the program statement that names the constant and declares 
its value and then recompile the program. 


5.3.1 Naming Constants Within a Program Unit 


You name constants within a program unit with the DECLARE statement. For example: 


169 DECLARE DOUBLE CONSTANT Preferred_rate = .147 
DECLARE SINGLE CONSTANT Normal_lrate = .162 
DECLARE DOUBLE CONSTANT Risky_rate = .175 
! 
I 
! 
500 New_bal = Old_bal * (1 + Preferred_rate)“Years_Payment 
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When interest rates change, only three lines have to be changed rather than every line that contains 
an interest rate constant. 


Constant names must conform to the rules for naming internal, explicitly declared variables listed in 
Section 6.1. No constant name can have embedded spaces. 


The value associated with a 


SS OUST VV 


value. For example: 


named constant can be ime expression as well as a literal 


m 
Cc) 
je) 
o, 
oD 
t 
ot 


100 DECLARE STRING CONSTANT Congrats = g. 
bh me ee ee ee ee ee +" + LF + CR + & 
"| Congratulations! i" + CR + CR + & 
Ng oe ee a Se 4+" 
! 
! 
! 

300 PRINT Congrats 


! 
! 
! 
1000 PRINT Congrats 


Named constants can save you programming time (since you don’t have to retype the congratulations 
box every time you want to display it) and execution time (since the named constant is known at 
compile time). 


Allowable operators in DECLARE CONSTANT expressions include all valid arithmetic, relational, and 
logical operators except exponentiation. You cannot use built-in functions in DECLARE CONSTANT 
expressions. 


BASIC—PLUS—2 allows you to name floating-point, integer, and string constants, but floating-point 
constants cannot be named as expressions. Only STRING and INTEGER constants can be named as 
expressions in DECLARE CONSTANT statements. VAX—11 BASIC allows constants of all data types to 
be named as expressions. For example: 


100 DECLARE DOUBLE CONSTANT & 
MIN .VALUE = O+ & 
MAX_VALUE = PI/2 


This example is valid only in VAX—11 BASIC. 


Note that you can specify only one data type in a DECLARE CONSTANT statement. To declare a 
constant of a different data type, you must use a second DECLARE CONSTANT statement. 


5.3.2 Naming Constants External to a Program Unit 


To declare constants outside the program unit, use the EXTERNAL statement. For example: 


200 EXTERNAL LONG CONSTANT SS#_NORMAL 
EXTERNAL WORD CONSTANT I5.SUC 


The first line declares the VAX/VMS status code SS$_NORMAL to be an external LONG constant. 
The second line declares IS.SUC, a success code, to be an external WORD constant. Note that 
VAX-11 BASIC allows external BYTE, WORD, LONG, and SINGLE constants, while BAS/C—PLUS—2 
allows only external WORD constants. The linker or task builder supplies the values for the constants 
specified in EXTERNAL statements. 
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External constant names cannot exceed six characters in BASIC~PLUS—2 and 31 characters in 
VAX—11 BASIC and must conform to the rules for naming external variables listed in Section 6.1. No 
constant name can have embedded spaces. 


The types of external constants you can refer to vary from system to system. In VAX—11 BASIC, the 
named constant might be a system status code or a global constant declared in a VAX—11 MACRO or 
VAX—11 BLISS program. In BASIC—PLUS—2, the named constant might be a global constant declared 
in a MACRO-11 program or an RMS constant. See the user’s guide for your system for more informa- 
tion on external constants available to your programs. 


5.4 Explicit Literal Notation 


You can specify the value and data type of numeric literals by using a special notation. The format of 
this notation in VAX—11 BASIC is: 


[radix] num-str-lit [data-type] 
Radix specifies an optional base. 
In VAX-11 BASIC, radix can be: 
¢D Decimal (base 10) 
eB Binary (base 2) 


¢©O Octal (base 8) 


eX Hexadecimal (base 16) 


The VAX—11 BASIC default radix is D, but you can also specify binary, octal, and hexadecimal 
integer literals. Binary, octal, and hexadecimal notation allows you to set or clear individual bits in 
the representation of an integer. This feature is useful in forming conditional expressions and in using 
logical operations. 


In BASIC-PLUS—2, num-str-lit is always treated as decimal (base 10), so the format for explicit literal 
notation in BASIC—PLUS—2 Is: 


num-str-lit [data-type] 
Num-str-lit is a quoted string that can consist of digits and an optional decimal point when the radix is 


decimal. You can also use E notation for floating-point constants. A leading minus sign cannot appear 
inside the quotation marks, but can appear before the radix. 


In VAX—11 BASIC, num-str-lit can be the digits 0 and 1 when the radix is binary, the digits 0 through 7 
when the radix is octal, and the digits 0 through F when the radix is hexadecimal. 


Data-type is an optional single letter that corresponds to a data-type keyword, excluding INTEGER 
and REAL: 


eB BYTE 

eW WORD 
eL LONG 
eF SINGLE 


(continued on next page) 
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eD DOUBLE 

¢G GFLOAT (VAX-11 BASIC only) 

eH HFLOAT (VAX—11 BASIC only) 

eP DECIMAL (VAX—17 BASIC only) 

For example: 
M255". Specifies a LONG decimal constant with a value of 255. 
“4000''F Specifies a SINGLE decimal constant with a value of 4000. 
—125"B Specifies a BYTE decimal constant with a value of —125. 


A quoted numeric string alone, without a radix and a data-type, is a string literal, not a numeric 
literal. For example: 


255” W Specifies a WORD decimal constant with a value of 255. 


“22 Is a string literal. 


In VAX—11 BASIC, if you specify a binary, octal, or hexadecimal radix, data-type must be an integer. 
If you do not specify a data type, BASIC uses the default integer data type. For example: 


B‘'11111111"B Specifies a BYTE binary constant with a value of —1. 
B’11111111’W — Specifies a WORD binary constant with a value of 255. 


BY‘'11111111” Specifies a binary constant of the default data type (BYTE, WORD, or LONG). 
B‘'11111111"F Is illegal because F is not an integer data type. 

X“FF’'B Specifies a BYTE hexadecimal constant with a value of —1. 

XFF’"W Specifies a WORD hexadecimal constant with a value of 255. 

X‘FF’D Is illegal because D is not an integer data type. 

O"377"B Specifies a BYTE octal constant with a value of —1. 

0377" W Specifies a WORD octal constant with a value of 255. 

O"377"G Is illegal because G is not an integer data type. 


When you specify a radix other than decimal, VAX—11 BASIC treats the numeric string as an unsigned 
integer. When, however, this value is assigned to a variable or used in an expression, VAX—11 BASIC 
treats the variable as a signed integer. For example: 


100 DECLARE BYTE A 
A = B"11111111"B 
PRINT A 

RUNNH 


ae 


In this example, VAX—11 BASIC sets all eight bits in storage location A. Because A is a BYTE integer, it 
has only 8 bits of storage and its value is —1 (the 8—bit two’s complement of 1 is 11111111). If the 
data type were W (WORD), VAX—71 BASIC would set the bits to 0000000011111111, and its value 
would be 255. 
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Note that in VAX—77 BASIC a D can appear in both the radix position and the data type position. D in 
the radix position specifies that the numeric string is to be treated as a decimal number (base 10). D in 
the data type position specifies that the value is to be treated as a double-precision, floating-point 
constant. A P in the data type position specifies a packed decimal constant. For example: 


“255"D Specifies a double-precision constant with a value of 255. 


“255.55’"P Specifies a DECIMAL constant with a value of 255.55. 


You can also use explicit literal notation to represent a single-character string in terms of its 8—bit 
ASCII value. The format in VAX—11 BASIC is: 


[radix] num-str-lit C 
The format in BASIC—PLUS-2 is: 
num-str-lit C 


The letter C is an abbreviation for CHARACTER. The value of the numeric string must be between 0 
and 255, inclusive. 


This feature lets you create your own compile-time string constants containing nonprinting charac- 
ters. For example: 


160 DECLARE STRING CONSTANT CONTROL_G = "7"C 
PRINT CONTROL_G 


This example declares a string constant named CONTROL_G (ASCII decimal value 7). When BASIC 
executes the PRINT statement, the terminal bell sounds. 


See the BASIC User’s Guide for more information on explicit literal notation. 


5.5 Predefined Constants 


Predefined constants are symbolic representations of either: 1) ASCII characters or 2) mathematical 
values. They are also called compile-time constants because their value is known at compile time 
rather than at run time. Predefined constants: 


e Format program output to improve readability 


® Make source code easier to understand 
Table 4 lists predefined constants supplied by BASIC, their ASCII values, and their purposes. 


Table 4: Predefined Constants 


Constant Purpose 


BEL (Bell) Sounds the terminal bell 


BS (Backspace) Moves the cursor one position to the left 


HT (Horizontal Tab) Moves the cursor to the next horizontal tab stop 


(continued on next page) 


BASIC Reference Manual 23 


> 


Table 4: Predefined Constants (Cont.) 


Decimal 
ASCII 
Constant Value 


LF (Line Feed) Moves the cursor to the next line 

VT (Vertical Tab) Moves the cursor to the next vertical tab stop 

FF (Form Feed) Moves the cursor to the start of the next page 

CR (Carriage Return) Moves the cursor to the beginning of the current line 

SO (Shift Out) Shifts out for communications networking, screen formatting, and alternate graphics 
SI (Shift In) Shifts in for communications networking, screen formatting, and alternate graphics 
ESC (Escape) Marks the beginning of an escape sequence 

SP (Space) Inserts one blank space in program output 


DEL (Delete) Deletes the last character entered 


PI Represents the number PI with the precision of the default floating-point data type 


You can use predefined constants in many ways. For example, to print and underline a word on a 
hard copy terminal: 


110 PRINT "NAME:" + BS + BS + BS + BS + BS + "__l___ *t 
120 END 

RUNNH 

NAME > 


190 PRINT ESC + "C4mNAME:" + ESC + "LOm" 
110 END 

RUNNH 

NAME: 


Note that the ‘‘m’’ in the above example must be lowercase. 


You can also create your own predefined constants with the DECLARE CONSTANT statement. For 
example: 


10 DECLARE STRING CONSTANT Underlined_name = ESC + "C4mNAME:" + ESC + "COm" 
20 DECLARE DOUBLE CONSTANT D_PI = PI 
30 PRINT Underlined name 

PRINT DIPI+>+PI 


Line 10 defines Underlined_name as a string constant equivalent to the constant displayed by line - 
100 in the previous example. Line 20 defines D_PI as a DOUBLE constant equal to the predefined 
constant PI. If the default REAL data size is SINGLE, the program can use both single-precision PI and 
double-precision D_PI. See the BASIC User’s Guide for more information on predefined constants 
and their use in BASIC programs. 
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6.0 Variables 


A variable is a named quantity whose value can change during program execution. Each variable 
name refers to a location in the program’s storage area. Each location can hold only one value at a 
time. Variables of all data types can have subscripts that indicate their position in an array. 


Depending on the program operations specified, the value of a variable can change from statement to 
statement. BASIC uses the most recently assigned value when performing calculations. This value 
remains until another statement assigns a new value to the variable. 


You can declare variables implicitly or explicitly. 
BASIC accepts these general types of variables: 

@ Floating-point 

e Integer 

® String 

@ RFA 

@ Packed Decimal (VAX—i7 BASIC only) 

@ Record (VAX—17 BASIC only) 


See Chapter 9 in the BASIC User’s Guide for more information on RFA variables and Chapter 6 in 
BASIC on VAX/VMS Systems for more information on record data structures. 


6.1 Variable Names 


The name given to a variable depends on whether the variable is internal or external to the program 
and whether the variable is implicitly or explicitly declared. 


1. The name of an internal, explicitly declared variable must conform to the following rules: 


e The name consists of from 1 to 31 characters. 


e The first character of the name must be an upper- or lowercase alphabetic character (A 
through Z). 


@ The last character of the name cannot be a dollar sign ($) or a percent sign (%). 


@ The remaining characters, if present, can be any combination of upper- or lowercase letters 
(A through Z), numbers (0 through 9), dollar signs ($), underscores (_), or periods (.). The use 
of underscores in variable names helps improve readability and is preferred to the use of 
periods. 


2. The name of an internal, implicitly declared variable must conform to the following rules: 


® The name consists of from 1 to 31 characters. 


@ The first character of the name must be an upper- or lowercase alphabetic character (A 
through Z). 


@ The last character of the name can be either a dollar sign ($) to indicate a string variable or a 
percent sign (%) to indicate an integer variable. If the last character is neither a dollar sign 
nor a percent sign, the name indicates a variable of the default type. 
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e The remaining characters, if present, can be any combination of upper- or lowercase letters 
(A through Z), numbers (0 through 9), dollar signs ($), underscores (_), or periods (.). The use 
of underscores in variable names helps improve readability and is preferred to the use of 
periods. 


3. The name of an external, explicitly declared variable in VAX—11 BASIC must follow the rules 
for naming an internal, explicitly declared variable. 


4. The name of an external, explicitly declared variable in BASIC-~PLUS—2 must conform to the 
following rules: 


@ The name consists of from one to six characters. 


© The first character of the name must be an upper- or lowercase alphabetic character (A 
through Z). 


@ The remaining characters, if present, can be any combination of upper- or lowercase letters 


(A through Z), numbers (0 through 9), dollar signs ($), or periods (.). 


5. A program cannot have external, implicitly declared variables since all implicitly declared 
names except SUB subprogram names are internal to the program. 


In all cases, no variable name can have embedded spaces. 


6.2 Implicitly Declared Variables 


BASIC accepts three types of implicitly declared variables: 


@ Floating-point (or default data type) 
® Integer 


@ String 


The name of an implicitly declared variable defines its data type. Integer variables end with a percent 
sign (%), string variables end with a dollar sign ($), and variables of the default type (usually floating- 
point) end with any allowable character except a percent sign or dollar sign. All three types of 
variables must conform to the rules listed in Section 6.1 for naming variables. The current data-type 
default (INTEGER, REAL, or, in VAX—11 BASIC, DECIMAL) determines the data type of implicitly 
declared variables that do not end in a percent sign (%) or dollar sign ($). 


A floating-point variable is a named location that stores a single floating-point value. The current 
default size for floating-point numbers (SINGLE, DOUBLE, or, in VAX-11 BASIC, GFLOAT or 
HFLOAT) determines the data type of the floating-point variable. The following are valid floating- 
point variable names: 


CG L6c5 ID_NUMBER 
M1 BIG47 STORAGE.LOCATION.FOR.XX 
F67T.J Z2. STRESS_VALUE 


If a numeric value of a different data type is assigned to a floating-point variable, BASIC converts the 
value to a floating-point number. 
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An integer variable is a named location that stores a single integer value. The current default size for 
integers (BYTE, WORD, or LONG) determines the data type of an integer variable. The following are 
valid integer variable names: 


ABCDEFG%  C_8% RECORD.NUMBER% 
B% D6E7% THE. VALUE.I.WANT% 
If the default data type is INTEGER, the percent suffix (%) is not necessary. 


If you assign a floating-point or decimal (VAX—11 BASIC only) value to an integer variable, BASIC 
truncates the fractional portion of the value. It does not round to the nearest integer. For example: 


100 BA = -5.7 


BASIC assigns the value —5 to the integer variable, not —6. 


A string variable is a named location that stores strings. The following are valid string variable names: 


C1$ M$ EMPLOYEE_NAME$ 
L.6$ F34G$ TARGET.RECORD$ 
ABC1$ T..$ STORAGE_SHELF_IDENTIFIER$ 


Strings have both value and length. BASIC sets all string variables to a default length of zero before 
program execution begins, except those ina COMMON, MAP, or virtual array. See Sections 5.0 and 
35.0 in Part IV of this manual for information on string length in COMMON and MAP areas. See the 
BASIC User’s Guide for information on default string length in virtual arrays. 


During execution, the length of a character string associated with a string variable can vary from zero 
(signifying a null or empty string) to 65535 characters in VAX—171 BASIC or 32767 characters in 
BASIC—PLUS—2. . 


6.3 Explicitly Declared Variables 


In addition to implicitly declared variables described in the previous sections, BASIC lets you explic- 
itly assign a data type to a variable or an array. For example: 


100 DECLARE DOUBLE Interest_rate 


Data-type keywords are described in Section 4.0. For more information on explicit declaration of 
variables, see the sections on COMMON, DECLARE, DIMENSION, DEF, FUNCTION, EXTERNAL, 
MAP, and SUB in Part IV of this manual and Chapter 5 in the BASIC User’s Guide. 


6.4 Subscripted Variables and Arrays 


A subscripted variable is part of an array. Arrays can be of any valid data type. Subscripted variables 
and arrays follow the same naming conventions as nonsubscripted variables. Subscripts follow the 
variable name in parentheses and define the variable’s position in the array. When you create an 
array, bounds follow the array name in parentheses and define the maximum size of the array. For 
example: 


100 DECLARE STRING Emp_name( 1000) 
200 FOR I% = 0% TO 1000% 
INPUT "“Emplovee name" sEmrp_name(I%) 
NEXT 1% . 
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The DECLARE statement in the example on the previous page sets the bounds of array Emp—name to 
1000. Thus, the maximum value for an Emp—name subscript is 1000. The bounds of the array define 
the maximum value for a subscript of that array. 


In VAX—11 BASIC, subscripts can be any positive integer value from 0 to 2147483646 in LONG 
mode. In BASIC—PLUS—2, subscripts can be any non-negative integer value from 0 to 32766. 


Note 


The compiler signals an error if a subscript is bigger than the allowable range. Also, 
the amount of storage the system can allocate depends on available memory. There- 
fore, very large arrays may cause an internal allocation error. 


An array is a set of data ordered in any number of dimensions. A one-dimensional array, like 
Emp_—name(1000), is called a list or vector. A two-dimensional array, like Payroll_data(5,5), is called 
a matrix. An array of more than two dimensions, like Big_array(15,9,2), is called a tensor. 


BASIC arrays are always zero-based. That is, the number of elements in any dimension always 
includes element number zero. For example, the array Emp—name(1000) contains 1001 elements, 
since BASIC allocates element zero. Payroll_data(5,5) contains 36 elements because BASIC always 
allocates row and column zero. 


For all arrays except virtual arrays, the total number of array elements cannot exceed 2147483647 
in VAX-11 BASIC and 32767 in BASIC—PLUS—2. For example, VAX—11 BASIC allows array 
A(2147483646) but does not allow array A(1,2147483646). BASIC-PLUS—2 allows array A(32766) 
but does not allow array A(1,32766). 


VAX-11 BASIC arrays can have up to 32 dimensions. BASIC—PLUS—2 arrays can have up to eight 
dimensions. You can also specify the type of data the array contains with data-type keywords. Table 2 
lists BASIC data types. 


An element in a one-dimensional array has a variable name followed by one subscript in parentheses. 
There can be a space between the array name and the parenthetical subscripts. For example: 
A(6%) 
B (6%) 
C$ (6%) 


A(6%) refers to the seventh item in this list: 

A(0%) A(1%) A(2%) A(3%) A(4%) A(5%) A(6%) 
An element in a two-dimensional array has two subscripts, in parentheses, following the variable 
name. The first subscript specifies the row number, the second specifies the column. Use a comma to 


separate the subscripts. There can be a space between the array name and the parenthetical sub- 
scripts. For example: 


A (7% ,2%) A%(4%,6%) A$(10%,10%) 
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In the following table, the arrow points to the element specified by the subscripted variable 
A%(4%,6%): 


COLUMN S 
0123 4 5 6 
RO 0000000 
O1 0000000 
W2 000000 0 
S$ 3 000000 0 
400000000 — A%(4%,6%) 


An element in an array has as many subscripts as there are dimensions. An element of 
Big_array(15%,9%,2%), for example, would have three subscripts. 


Although a program can contain a variable and an array with the same name, this is regarded as poor 
programming practice. Variable A and the array A(33%,3%) are separate entities and are stored in 
completely separate locations and should have different names. 


Note 


A program cannot contain two arrays with the same name and a different number of 
subscripts. For example, the arrays A(3%) and A(3%,3%) are invalid in the same 
program. 


BASIC arrays can be redimensioned at run time. See Chapter 7 in the BASIC User’s Guide for more 
information on arrays. 


6.5 Initialization of Variables 


BASIC sets variables to zero or null values at the start of program execution. Variables initialized by 
BASIC include: 


e Numeric variables and in-storage array elements (except those in MAP or COMMON statements). 
¢ String variables (except those in MAP or COMMON statements). 


e Local variables in function definitions. In addition, BASIC sets these values to zero each time the 
program Calls the function. 


e Variables in subprograms. Subprogram variables are initialized to zero or the null string each time 
the subprogram is called. 


BASIC does not initialize virtual arrays. 


Note 


In BASIC—PLUS—2, variables in a MAP statement referenced in an OPEN statement are 
initialized to zero or the null string when the file is opened. In VAX—11 BASIC, these 
variables are not initialized. You can also use MACRO—11 routines to initialize MAP 
and COMMON areas. See BASIC on RSX-11M/M-—PLUS Systems or BASIC on RSTS/E 
Systems for more information. 
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7.0 Expressions 


BASIC expressions consist of operands (numbers, strings, constants, variables, functions, or array 
elements) separated by: 


e Arithmetic operators 
e String operators 
e Relational operators 


e Logical operators 


All BASIC expressions except string concatenation and invocations of string-valued functions yield 
numeric values. The way you combine numeric operators and operands and use the resulting values 
allows you to produce: 


e Numeric expressions 
e String expressions 


e Conditional expressions 


BASIC evaluates expressions according to operator precedence and uses the results in program execu- 
tion. Parentheses can appear in expressions to group operands and operators, thus controlling the 
order of evaluation. 


The following sections explain the types of expressions you can create and the way BASIC evaluates 
expressions. 


7.1 Numeric Expressions 


Numeric expressions consist of floating-point, integer, or packed decimal (VAX—11 BASIC only) 
operands separated by arithmetic operators and optionally grouped by parentheses. Table 5 shows 
how numeric operators work in numeric expressions. 


Table 5: Arithmetic Operators 


[ome [ome [ 


Add BtoA 


Subtract B from A 


Multiply A by B 
Divide A by B 


Raise A to the power B 


Raise A to the power B 


In general, two arithmetic operators cannot occur consecutively in the same expression. EAcepuOnS 
are the unary plus and unary minus. The following expressions are valid: 


A*+B 
A*—B 
A * (-B) 
Ae po OB 
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The following expression is not valid: 
A-—*B 

An operation on two numeric operands of the same data type yields a result of that type. For example: 
A% + B% yields an integer value of the default type. 
G3 * M5 yields a floating-point value if the default type is REAL. 


If the result of the operation exceeds the range of the data type, VAX—11 BASIC signals an overflow 
error message. For example: 


10 DECLARE BYTE A: B 
A = 127 
B = 127 
PRINT A + B 

99 END 


This example causes VAX—11 BASIC to signal the error ‘‘Integer error or overflow’ because the sum of 
A and B (254) exceeds the range of —128 to + 127 for BYTE integers. Similar overflow errors occur for 
REAL and DECIMAL data types whenever the result of a numeric operation is outside the range of the 
data type. 


Assigning a value of one data type to a variable of a different data type changes the assigned value’s 
data type to the variable’s data type. For example: 


10 AZ = 3-1 * 6.3 


This example assigns the value 32 to the integer variable A% even though the floating-point value of 
the expression is 32.13. This is called numeric conversion. See Chapter 5 of the BASIC User’s Guide 
for more information on numeric conversion. 


7.1.1 Floating-Point and Integer Promotion Rules 


When an expression contains operands with different data types, the data type of the result is deter- 
mined by BASIC’s data type promotion rules: 


® With one exception, BASIC promotes operands with different data types to the lowest common data 
type that can hold the largest or most precise possible value of either operand’s data type, then 
performs the operation in that data type, and yields a result of that data type. 


e The exception to the previous rule is that when an operation involves SINGLE and LONG data 
types, BASIC promotes the LONG data type to SINGLE, rather than to DOUBLE, performs the 
operation, and yields a result of the SINGLE data type. 


Note that BASIC does a sign extend when converting BYTE and WORD integers to a higher INTEGER 
data type (WORD or LONG). That is, the high order bit (the sign bit) determines how the additional 
bits are set when the BYTE or WORD is converted to WORD or LONG. If the high order bit is zero 
(positive), all higher-order bits in the converted BYTE or WORD are set to zero. If the high order bit is 
one (negative), all higher-order bits in the converted BYTE or WORD are set to one. 


Table 6 lists the data type results possible in numeric expressions that combine BYTE, WORD, 
LONG, SINGLE, and DOUBLE data. Table 7 lists the data type results possible in numeric expres- 
sions that combine the VAX—11 BASIC only data types, GFLOAT and HFLOAT. Note that in VAX—11 
BASIC, when the operands are DOUBLE and GFLOAT, BASIC promotes both values to HFLOAT, and 
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returns an HFLOAT value. The promotion of DOUBLE and GFLOAT to HFLOAT is necessary because 
a DOUBLE value is more precise than a GFLOAT value, but cannot contain the largest possible 
GFLOAT value. Consequently, BASIC promotes these data types to a data type that can hold the 
largest and most precise value of either operand. 


Table 6: Result Data Types in BASIC Expressions 


Operand 2 


Operand 1 BYTE WORD LONG SINGLE DOUBLE 


BYTE BYTE WORD LONG SINGLE DOUBLE 
WORD WORD WORD LONG SINGLE DOUBLE 
LONG LONG LONG LONG SINGLE DOUBLE 
SINGLE SINGLE SINGLE SINGLE SINGLE DOUBLE 
DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE 


Table 7: VAX—11 BASIC Result Data Types 


Operand 2 


Operand 1 GFLOAT HFLOAT 


BYTE GFLOAT HFLOAT 
WORD GFLOAT ~ HFLOAT 


LONG GFLOAT  HFLOAT 
SINGLE GFLOAT ~ HFLOAT 
DOUBLE HFLOAT HFLOAT 
GFLOAT GFLOAT ~ HFLOAT 
HFLOAT HFLOAT  HFLOAT 


As Table 6 shows, if one operand is SINGLE and one operand is DOUBLE, BASIC promotes the 
SINGLE value to DOUBLE, performs the specified operation, and returns the result as a DOUBLE 
value. This promotion is necessary because the SINGLE data type has less precision than the 
DOUBLE value, whereas the DOUBLE data type can represent all possible SINGLE values. If BASIC 
did not promote the SINGLE value and the operation yielded a result outside of the SINGLE range, 
loss of precision and significance would occur. 


The data types BYTE, WORD, LONG, SINGLE, and DOUBLE form a simple hierarchy: if all operands 
in an expression are these data types, the result of the expression is the highest data type used in the 
expression. 


7.1.2 DECIMAL Promotion Rules (VAX—11 BASIC only) 


VAX-11 BASIC also allows the DECIMAL(d,s) data type. The number of digits (d) and the scale or 
position of the decimal point (s) in the result of operations involving a DECIMAL value depends on the 


32 BASIC Reference Manual 


data type of the other operand. If one operand is DECIMAL and the other is DECIMAL or INTEGER, 
the d and s values of the result are determined as follows: 


@ If both operands are typed DECIMAL, and if both operands have the same digit (d) and scale (s) 


wale ‘ ath lt vf t i 
values, no Conversions occur and the result of the operation has exactly the same d and s values as 
S 


the d value. 


e If both operands are DECIMAL but have different digit and scale values, BASIC always uses the 
larger number of specified digits for the result. 


For example: 


100 DECLARE DECIMAL(3:+2) A 
DECLARE DECIMAL(4;3) B 


Variable A allows three digits to the left of the decimal point and two digits to the right. Variable B 
allows one digit to the left of the decimal point and three digits to the right. Therefore, the result 
allows three digits to the left of the decimal point and three digits to the right: 


A Sexi 
i fo 


Result ee 


@ If one operand is typed DECIMAL and one is typed INTEGER, the INTEGER value is converted to a 
DECIMAL(d,s) data type as follows: 


BYTE is converted to DECIMAL(3,0). 
WORD is converted to DECIMAL(5,0). 
LONG is converted to DECIMAL(10,0). 


BASIC then determines the d and s values of the result by evaluating the d and s values of the 
operands as described above. 


Note that only INTEGER data types are converted to the DECIMAL data type. If one operand is 
DECIMAL and one is floating-point, the DECIMAL value is converted to a floating-point value. The 
total number of digits (d) in the DECIMAL value determines its new data type, as shown in Table 8. 


Table 8: Result Data Types for DECIMAL Data 


Number of Floating-point Operands 
DECIMAL Digits 
in Operand SINGLE DOUBLE GFLOAT  HFLOAT 


SINGLE DOUBLE GFLOAT  HFLOAT 
DOUBLE DOUBLE GFLOAT ~~ HFLOAT 
DOUBLE DOUBLE HFLOAT ~ HFLOAT 
HFLOAT HFLOAT HFLOAT ~~ HFLOAT 


BASIC Reference Manual 33 


If the value of d is between 7 and 15, the operand is converted to: 

e DOUBLE if the floating-point operand is SINGLE or DOUBLE 

e GFLOAT if the floating-point operand is GFLOAT 

@ HFLOAT if the floating-point operand is HFLOAT 

Thus, a DECIMAL(8,5) operand is converted to DOUBLE if the other operand is SINGLE or DOUBLE, 
to GFLOAT if the other operand is GFLOAT, and to HFLOAT if the other operand is HFLOAT. 
Note also that exponentiation of a DECIMAL data type returns a REAL value. 


See the BASIC User’s Guide for more information on data type interactions, conversions, and promo- 
tion rules in BASIC numeric expressions. 


7.2 String Expressions 


String expressions are string entities separated by the plus sign (+). When used in a string expression, 
the plus sign concatenates strings. 


For example: 

190 INPUT "Type two words to be combined"sA%; Bt 
CH = A&® + BSF 
PRINT CS 

200 END 

RUNNH 


Type two words to be combined? hello 
7 goodbye 


hellogoodbve 


Ready 


7.3 Conditional Expressions 


Conditional expressions can be either relational or logical expressions. 


Numeric relational expressions compare numeric operands to determine whether the expression is 
true or false. String relational expressions compare string operands to determine which string expres- 
sion occurs first in the ASCII collating sequence. 


Logical expressions contain integer operands and logical operators. BASIC determines whether the 
specified logical expression is true or false by testing the numeric result of the expression. Note that in 
conditional expressions, as in any numeric expression, when BYTE and WORD operands are con- 
verted to WORD and LONG, the specified operation is performed in the higher data type, and the 
result returned is also of the higher data type. When one of the operands is a negative value, this 
conversion will produce accurate but perhaps confusing results, because BASIC performs a sign 
extend when converting BYTE and WORD integers to a higher integer data type. See Section 7.1.1 for 
information on integer conversion rules. 
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7.3.1 Numeric Relational Expressions 


Operators in numeric relational expressions compare the values of two operands and return: 1) a 
minus one if the relation is true or 2) a zero if the relation is false. The data type of the result is the 
default integer type. For example: 


Example 1 

100 A = 10 
B= 15 
X% = (A <> B) 
IF XZ = -1% 


THEN PRINT ‘Re 
ELSE IF X% = 6 
THEN PRIN 
END IF 
END IF 


RUNNH 


Relationship is true 


Example 2 

10 A = 10 
B = 15 
X% = A= B 
IF X% = -1% 


THEN PRINT ‘Relati 

ELSE IF X% = 0 
THEN PRINT (‘R 
END IF 

END IF 


RUNNH 


Relationshie is false 


lationship is true’ 


T ‘Relationshie is false’ 


onshirF is true’ 


Plationshirp is false’ 


Table 9 shows how numeric operators work in numeric relational expressions. 


Table 9: Numeric Relational Operators 


Ecard osect AIL 


< 

> 
<=or=< 
>= or=> 
<> or>< 


A is equal to B. 
A is less than B. 


A is greater than B. 


A is less than or equal to B. 


A is greater than or equal to B. 
A is not equal to B. 


A and B will PRINT the same because 
they are equal to six significant digits. 
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7.3.2 String Relational Expressions 


Operators in string relational expressions determine how BASIC compares strings. BASIC determines 
the value of each character in the string by converting it to its ASCil value. ASCII values are listed in 
Appendix C in BASIC on VAX/VMS Systems, BASIC on RSX—11M/M—PLUS Systems, and BASIC on 
RSTS/E Systems. BASIC compares the strings character by character, left to right, until it finds a 
difference in ASCII value. For example: 


10 A% = ‘ABC’ 


20 IF AS < Bt 
THEN PRINT ‘ABC comes before ABZ’ 
GOTO 99 
ELSE IF At == BS 
THEN PRINT ‘The strings are identical ’ 
GOTO 99 
ELSE IF At > BS 
THEN PRINT ‘ABC comes after ABZ’ 


GOTO 99 
END IF 
END IF 
END IF 
55 PRINT ‘Strings are esaual but not identical’ 


99 END 


In this example, BASIC compares A$ and B$ character by character. The strings are identical up to 
the third character. Because the ASCII value of ‘’Z’’ (90) is greater than the ASCII value of “‘C’’ (67), 
A$ is less than B$. BASIC evaluates the expression A$ < B$ as true (—1), prints ‘“ABC comes before 
ABZ” and goes to line 99. 


lf two strings of differing lengths are identical up to the last character in the shorter string, BASIC pads 
the shorter string with spaces (ASCII value 32) to generate strings of equal length, unless the operator 
is the double equals sign (= =). If the operator is the double equals sign, BASIC does not pad the 
shorter string. For example: 


19 AS = “’ABCDE’ 
BS = ‘ABC’ 
20 PRINT ‘BS comes before A#’ IF BS < Aft 
PRINT ‘A#® comes before BS’ IF AS < Bt 
30 CH = ‘ABC “ 
IF BS == CH 
THEN PRINT ‘BS exactly matches C#’ 
ELSE PRINT ‘’B# does not exactly match C#’ 


THEN PRINT ‘BS matches CH with Padding’ 
ELSE PRINT ‘B# does not match CH’ 


RUNNH 


BS comes before AS 
BS does not exactly match CH 
BS matches C# with Padding 


In this program, BASIC compares ‘““ABCDE” to ‘‘ABC " to determine which string comes first in the 
collating sequence. ““ABC  "’ comes before ‘“ABCDE”’ because the ASCII value for space (32) is lower 
than the ASCII value of ““D’ (68). Then BASIC compares “ABC ” with ‘ABC’ using the double 
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equals sign and determines that the strings do not match exactly without padding. The third compari- 
son uses the single equals sign. BASIC pads ‘‘ABC”’ with spaces and determines that the two strings 
match with padding. 


Table 10 shows how numeric operators work in string relational expressions. 


Table 10: String Relational Operators 


SS =. 


= Strings A$ and B$ are identical after the shorter string has been padded with spaces to 
equal the length of the longer string. 


String A$ occurs before string B$ in ASCII sequence. 


String A$ occurs after string B$ in ASCII sequence. 


String A$ is identical to or precedes string B$ in ASCII sequence. 
String A$ is identical to or follows string B$ in ASCII sequence. 
String A$ is not identical to string B$. 


Strings A$ and B$ are identical in composition and length, without padding. 


BASIC treats unquoted strings typed in response to the INPUT statement differently than quoted strings 
by ignoring leading and trailing spaces and tabs. That is, BASIC evaluates the quoted strings ‘“ABC” 
and “ABC ” as equal but not identical because the = = operator does not pad the shorter string 
with spaces. When you input the same strings as unquoted strings in response to the INPUT prompt, 
BASIC evaluates them as equal and identical because it ignores the trailing spaces. The LINPUT 
statement, on the other hand, treats unquoted strings as string literals so the trailing spaces are part of 
the string, and BASIC evaluates the strings as equal but not identical. 


7.3.3 Logical Expressions 

A logical expression contains either: 

e A unary logical operator and one integer operand 

e Two integer operands separated by a binary logical operator 


e One integer operand 


Logical expressions are valid only when the operands are integers. If the expression contains two 
integer operands of differing data types, the resulting integer has the same data type as the higher 
integer operand. For instance, the result of an expression that contains a BYTE integer and a WORD 
integer would be a WORD integer. Table 6 shows how integer data types interact with each other in 
expressions. 


BASIC determines whether the condition is true or false by testing the result of the logical expression 
to see whether any bits are set. If no bits are set, the value of the expression is zero and it is evaluated 
as false; if any bits are set, the value of the expression is nonzero, and the expression is evaluated as 
true. BASIC generally accepts any nonzero value in logical expressions as true. However, logical 
operators can return unanticipated results unless minus one is specified for true values and zero for 
false. Therefore, logical operators should be used on the results of relational expressions to obtain 
valid and predictable results. Table 11 lists logical operators. Examples that show how logical opera- 
tors work on nonzero and minus one values follow the table. 


BASIC Reference Manual 37 


Table 11: Logical Operators 


NOT A% The bit-by-bit complement of A%. If A% is true (1), NOT A% is false (0). 


A% AND B% | The logical product of A% and B%. A% AND B% is true only if both A% and B% are true. 


A% OR B% | The logical sum of A% and B%. A% OR B% is false only if both A% and B% are false; 
otherwise, A% OR B% is true. 


A% XOR B% | The logical exclusive OR of A% and B%. A% XOR B% is true if either A% or B% is true 
but not if both are true. 


A% EQV B% | The logical equivalence of A% and B%. A% EQV B% is true if A% and B% are both true 
or both false; otherwise, the value is false. 


A% IMP B% | The logical implication of A% and B%. A% IMP B% is false only if A% is true and B% is 
false; otherwise, the value is true. 


The truth tables in Table 12 summarize the results of these logical operations. Zero is false; minus one 
is true. 


Table 12: Truth Tables 


A% OR B% 


0 
=| 
+I 
+1 

A% EQV B% 


—1 


A% XOR B% 


0 
-1 
-1 

0 


The operators XOR and EQV are logical complements. 


Note that in logical expressions, any nonzero value is evaluated as true, while in relational expres- 
sions, a minus one is generated as a true value. Logical operators set bits in the result of the expres- 
sion; any bit set is a nonzero value and is evaluated as true. For this reason, it is important to use 
logical operators on the results of relational expressions (the values of minus one and zero) to avoid 
unanticipated results. For example: 


10 Ax = 2% 


2 
20 BY = 4% 
30 IF AZ THEN PRINT ’A% 15 TRUE’ 
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40 IF B% THEN PRINT ‘’B% I5 TRUE’ 

30 IF AZ AND BZ THEN PRINT ‘AX AND BA IS TRUE’ 
ELSE PRINT ‘A% AND B% IS FALSE’ 

60 END 


terete! 


AZ IS TRUE 
BZ IS TRUE 
AZ AND BZ IS FALSE 


In this example, the values of A% and B% both test as true because they are nonzero values. 
However, the logical AND of these two variables returns an unanticipated result of “false.”” 


The program returns this seemingly contradictory result because logical operators work on the indi- 
vidual bits of the operands. The 8—bit binary represeniation of 2% is: 


0000 0 0 1 0 
The 8-bit binary representation of 4% is: 
00000 1 0 0 


Each value tests as true because it is nonzero. However, the AND operation on these two values sets 
a bit in the result only if the corresponding bit is set in both operands. Therefore, the result of the 
AND operation on 4% and 2% is: | 


000 00 0 0 0 
No bits are set in the result, so the value tests as false (zero). 


If the value of B% is changed to 6%, the resulting value tests as true (nonzero) because both 6% and 
2% have the second bit set. Therefore, BASIC sets the second bit in the result and the value tests as 
nonzero and true. 


The 8—bit binary representation of minus one is: 


1 1 1 1 1 1 1 1 
i i 1 H i i ! i 


The result of -1% AND —1% is —1% because BASIC sets bits in the result for each corresponding bit 
that is set in the operands. The result, therefore, tests as true because it is a nonzero value. For 
example: 


-1% 

-1% 

30 IF AZ THEN PRINT ‘AZ 15 TRUE’ 

40 IF BZ THEN PRINT ’B% IS TRUE’ 

30 IF AX AND BZ THEN PRINT ‘AX AND BZ IS TRUE’ 
ELSE PRINT ’AZ AND BZ IS FALSE’ 


i 

o 

a 

xe 
woul 


60 END 


RUNNH 


A% 15 TRUE 
BZ IS TRUE 
AZ AND B% 15 TRUE 
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Your program may also return unanticipated results if you use the NOT operator with a nonzero 
operand that is not minus one. For example: 


10 AL=-1% 
20 Ba=2 
30 IF AZ THEN PRINT ‘AX IS TRUE’ 
ELSE PRINT ‘AZ IS FALSE’ 
40 IF BZ THEN PRINT ‘BA IS TRUE’ 
ELSE PRINT ‘’B% IS FALSE’ 
30 IF NOT AZ THEN PRINT ‘NOT AZ IS TRUE’ 
ELSE PRINT ‘NOT AZ IS FALSE’ 
60 IF NOT B% THEN PRINT ’NOT BZ IS TRUE’ 
ELSE PRINT ‘NOT BZ 15 FALSE’ 
99 END 


RUNNH 


AZ 15 TRUE 
B% IS TRUE 
NOT AZ IS FALSE 
NOT B% IS TRUE 


In this example, BASIC evaluates both A% and B% as true because they are nonzero. NOT A% is 
evaluated as false (zero) because the binary complement of minus one is zero. NOT B% is evaluated 
as true because the binary complement of two has bits set and, therefore, is a nonzero value. 


Note 


DIGITAL recommends that you use logical operators on the results of relational 
expressions to avoid obtaining unanticipated results. 


7.4 Evaluating Expressions 


BASIC evaluates expressions according to operator precedence. Each arithmetic, relational, and string 
operator in an expression has a position in the hierarchy of operators. The operator’s position tells 
BASIC when to perform the operation. Parentheses can change the order of precedence. 


Table 13 lists all operators as BASIC evaluates them. Note that: 


e Operators with equal precedence are evaluated logically from left-to-right. 


e BASIC evaluates expressions enclosed in parentheses first, even when the operator in parentheses 
has a lower precedence than that outside the parentheses. 
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Table 13: Numeric Operator Precedence 


Seon: pulses! 
— (unary minus) or + (unary plus) 

* or / 

+ or— 

+ (concatenation) 


all relational operators 


NOT 

AND 

OR, XOR 

IMP | 
EQV Lowest 


BASIC thus evaluates the expression A = 15°2 + 12*2 — (35 * 8) in five steps: 


1.0 15°2 = 225 Exponentiation (left-most expression) 
2. 12°2 = 144 Exponentiation 

3. 225 + 144 = 369 ~~ Addition 

4. (35 * 8) = 280 Multiplication 

5. 369-280 = 89 Subtraction 


There is one exception to this order of precedence: when an operator that does not require operands 
on either side of it (Such as NOT) immediately follows an operator that does require operands on both 
sides (such as +), BASIC evaluates the second operator first. For example: 


A% + NOT B% + C% 


This expression is evaluated as: 


(A% + (NOT B%)) + C% 


BASIC evaluates the expression NOT B before it evaluates the expression A + NOT B. When the 
NOT expression does not follow the + expression, the normal order of precedence is followed: 


NOT A% + B% + C% 


This expression is evaluated as: 


NOT ((A% + B%) + C %) 
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BASIC evaluates the two plus expressions (A% + B%) and ((A% + B%) + C%) because the plus (+) 
operator has a higher precedence than the NOT operator. 


BASIC evaluates nested parenthetical expressions from the inside out. For example: 


100 A = (00025 +73) 7 9) #7) + 3) 
PRINT A 

300 Be?25+S/5 #7 + 3 
PRINT B 

RUNNH 

43 

35 


In this program, BASIC evaluates the parenthetical expression A quite differently from expression B. 
For expression A, BASIC evaluates the innermost parenthetical expression (25 + 5) first, then the 
second inner expression (30 / 5), then (6 * 7), and finally (42 + 3). For expression B, BASIC evaluates 
(5 / 5) first, then (1 * 7), then (25 + 7 + 3) to obtain a different value. 
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PART Il 
Compller 
Commands 


APPEND 


1.0 APPEND 


Function 


The APPEND command merges an existing BASIC source program with the program currently in 
memory. 


Format 


| APPEND [ file-spec |] | 
Syntax Rules 


1. File-spec names the file of BASIC program lines you want to merge with the program 
currently in memory. The VAX—11 BASIC default file type is BAS, and the BASIC-PLUS—2 
default file type is B2S. 


General Rules 
1. If you type APPEND without specifying a file name, BASIC prompts with: 


Arrpend file name-- 


Respond with a file name. If you respond with a carriage return and no file name, VAX—11 
BASIC searches for a file named NONAME.BAS. BASIC—PLUS—2 searches for a file named 
NONAME.B2S. If the compiler cannot find NONAME.BAS or NONAME.B2S, VAX—11 
BASIC signals the error “file not found’; BASIC—PLUS—2 signals ‘‘can’t find file or 
account’. 
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APPEND 


2. You can append the contents of file-spec to a source program called into memory with the 
OLD command or created in the BASIC environment. If there is no program in memory, 
BASIC appends the file-spec to an empty program with the default file name, NONAME. 


3. If the file-spec contains a BASIC line with the same line number as a line of the program in 
memory, the line in the appended file replaces the line of the program in memory. Other- 
wise, BASIC inserts appended lines into the program in memory in sequential, ascending 
line number order. 


4. The APPEND command does not change the name of the program in memory. 


5. lf you have not saved the appended version of the program, BASIC signals the warning 
“Unsaved change has been made, CTRL/Z or EXIT to exit’’ the first time you try to leave 
the BASIC environment. 

Examples 


APPEND PROGB 
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ASSIGN 


2.0 ASSIGN (VAX-11 BASIC) 


= wees | = 7s owe 


Function 


The ASSIGN command equates a logical name to a complete file specification, a device, or another 
logical name within the context of the BASIC environment. 


Format 


ASSIGN equiv-nam[:] log-nam[:] 
Oe ee eee 
Syntax Rules 


1. Equiv-nam specifies the file specification, device, or logical name to be assigned a logical 
name. If you specify a physical device name, terminate it with a colon (:). 


2. Log-nam is the 1— to 63~character logical name to be associated with equiv-nam. You can 
specify a logical name for any portion of a file specification. If the logical name translates 
to a device name, and will be used in place of a device name in a file specification, 
terminate it with a colon (:). 


General Rules 


1. When the logical name assignment supersedes another logical name assigned previously, 
BASIC displays the message ‘‘previous logical name assignment replaced’’. 


2. If log-nam has more than 63 characters, BASIC signals the error “invalid logical name’’. 


3. Logical names assigned with the ASSIGN command are placed in the process logical name 
table and remain there until you exit the BASIC environment. 


Examples 


ASSIGN CLEONARD.BAS] PRO: 
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BRLRES 


3.0 BRLRES (BASIC—PLUS—2) 


Function 


The BRLRES command allows you to specify a memory-resident BASIC—PLUS—2 or user-created 
library to be used when you task-build the program. When you use the BUILD command, 
BASIC—PLUS-—2 includes the specified library in the Task Builder command file. The default library for 
the BRLRES command is chosen by your system manager when BASIC—PLUS-—2 is installed. 


Format 


BRLRES [ lib-param ] 


lib-param: file-spec 
NONE 


Syntax Rules 


1. If you enter the BRLRES command without a /ib-param, BASIC prompts for one and dis- 
plays the name of the current default memory-resident library. 


e File-spec can be a library supplied by BASIC—PLUS—2 or a user-created library. 


e NONE tells the Task Builder not to link your task to the BASIC-PLUS—2 default resident 
library. Therefore, the Task Builder links to the BASIC-PLUS—2 object module library, 
BP2OTS.OLB. 


e If you type a carriage return in response to the prompt, the current default memory- 
resident library is used. 


General Rules 


1. The memory-resident libraries supplied by BASIC—PLUS—2 are LB:[1,1]BP2RES and 
LB:[1,1]BP2SML on RSX—11M/M—PLUS systems and LB:BP2RES and LB:BP2SML on 
RSTS/E systems. LB: is a RSTS/E logical name for the library account on disk. Because 
memory-resident libraries are optional, your system manager can seiect none, one, or both 
when BASIC—PLUS-—2 is installed. See BASIC on RSX-11M/M-—PLUS Systems or BASIC on 
RSTS/E Systems for information on BASIC—PLUS—2 memory-resident libraries. 


2. BASIC—PLUS—2 links the specified memory-resident library to your program when you 
task-build the program, so you must use the BRLRES command before you use the BUILD 
command to include the specified library in the Task Builder command file. 


3. The BRLRES library you specify is included in your Task Builder command files until you 
specify a new library with the BRLRES command or exit from the BASIC environment. 
When you exit from the environment, the original default library is restored as the default. 


4. You can override the BRLRES command with the /BRLRES qualifier added to the BUILD 
command, but the specified library remains in effect for only one BUILD operation. 


46 BASIC Reference Manual 


BRLRES 


5. The Task Builder returns an error message when the requested memory-resident library is 
not available. 


6. Consult your system manager for information about the resident libraries available to you. 


Examples 
RSX-11M/M-—PLUS Systems 


BRLRES LB:Ci;+sl1JBP2RES 


BRLRES LB:BP2RES 
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BUILD 


4.0 BUILD (BASIC—PLUS—2) 


Function 


The BUILD command generates a command (CMD) file and an overlay description language (ODL) 
file for the Task Builder. The command file contains instructions that enable the Task Builder to link 
your program module(s) with libraries and other routines. The overlay description language file 
specifies how segments of the task-built program are overlaid when you run it. 


Format 


Syntax Rules 


1. Prog-nam names the program you want to build. If you do not specify a prog-nam, 
BASIC—PLUS—2 creates CMD and ODL files for the current program or for NONAME if 
there is no current program. 


2. Sub-nam names the subprogram or subprograms you want to link to the main program. 
You must specify a prog-nam if you specify a sub-nam. 


3. The command file takes the name of the main program and a default extension of CMD. 
The ODL file takes the name of the main program and a default extension of ODL. 


4.  /Qualifier specifies a qualifier keyword that sets a BASIC default. Table 17 lists all 
BASIC—PLUS-—2 qualifiers and describes their functions. 


5. The BUILD command line must fit on a single 80—character line. 


General Rules 


1. The BUILD command does not change the current context of the BASIC—PLUS—2 
environment. 


2. The BUILD command generates the CMD and ODL files. It does not cause the Task Builder 
to begin operation. 


3. In addition to program names and build qualifiers, the BUILD command accepts defaults 
from previously specified BRLRES, DSKLIB, ODLRMS, RMSRES, LIBR, and SET commands. 


4. BUILD qualifiers tell the Task Builder to perform special operations on object modules 
when you task-build the program. You can abbreviate all qualifiers to the first three letters 
of the qualifier keyword. 

Examples 


BUILD MAIN»SUB1 »SUB2 /DUMP/REL 
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$ Command 


5.0 $ Command 


Function 


You can enter a system command while in the BASIC environment by typing a dollar sign ($) before 
the command. BASIC passes the command to the operating system for execution. The context of the 
BASIC environment and the program currently in memory do not change in VAX-171 BASIC and 
BASIC—PLUS—2 on RSX—11M/M-—PLUS systems. On RSTS/E systems, the system command executes 
and control returns to the default run-time system, not to BASIC—PLUS-2. 


Format 


$ system-command 


Syntax Rules 


1. BASIC passes system-command directly to your operating system without checking for 
validity. 


General Rules 


1. The terminal displays any error messages or output that the system-command generates. 


VAX-11 BASIC 


1. Control returns to the BASIC environment after the system-command executes. The context 
(source file status, loaded modules, and so on) of the BASIC environment and the program 
currently in memory do not change unless the system-command causes the operating 
system to abort BASIC or log you out. 


2. On VAX/VMS systems, the system-command you specify executes within the context of a 
subprocess. Consequently, commands such as the DCL SET command execute only within 
the subprocess and do not affect the process running BASIC. 


BASIC—PLUS—2 


1. On RSX-11M/M-PLUS systems, control returns to the BASIC environment after the 
system-command executes. The context (source file status, loaded modules, and so on) of 
the BASIC environment and the program currently in memory do not change unless the 
system-command causes the operating system to abort BASIC or log you out. 


2. On RSTS/E systems, the context of the environment and the program currently in memory (RsTS) 
are lost. After the system command executes, control passes to monitor level, not to 
BASIC—PLUS-2. 


3. If you have made changes to the program currently in memory, BASIC—PLUS—2 displays 
the message ‘‘Unsaved change has been made — type SCRATCH or REPLACE” when you 
enter a system-command. 
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$ Command 


Examples 
VAX-—-11 BASIC 


Ready 


$SHOW PROTECTION 
SYSTEM=RWED» OWNER=RWED+ GROUP=RWED+ WORLD=RE 


Ready 


BASIC—PLUS—2 


$DIR STOCK.B2S 
ZUnsaved change has been made - type SCRATCH or REPLACE, 


BASIC2 
REPLACE 
BASIC2 


$DIR STOCK.B2S 
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COMPILE 


6.0 COMPILE 


Function 


The COMPILE command converts a BASIC source program to an object module and writes the object 
file to disk. 


Format 


| COMPILE [ file-spec ] [ /qualifier ]... | 


a ee aCe a a ee ee a ee ee es | 


Syntax Rules 


1. 


File-spec specifies a name for the output file or files. If you do not provide a file-spec, the 
compiler uses the name of the program currently in memory for the file name, a default file 
type of OBJ for the object file, and a default file type of LIS (VAX—17 BASIC) or LST 
(BASIC—PLUS—2) for the listing file, if a listing file is requested. BASIC-PLUS—2 uses a 
default file type of MAC for the macro source code file when a macro file is requested. 


In VAX—11 BASIC, file-spec can precede or follow /qualifier. In BASIC—PLUS—2, file-spec 
must precede the qualifiers. 


/Qualifier specifies a qualifier keyword that sets a BASIC default. See Section 22.0 for 
information on BASIC qualifiers. Table 16 lists and describes VAX—11 BASIC qualifiers. 
Table 17 lists and describes BASIC-PLUS—2 qualifiers. 


In cases of ambiguous or erroneous qualifiers, VAX—11 BASIC signals ‘‘Unknown quali- 
fier’, BASIC—PLUS-2 signals ‘Illegal switch’’, and the program does not compile. When 
qualifiers conflict, BASIC compiles the program using the last specified conflicting quali- 
fier. For example: 


COMPILE / OBJ /NOOBJ 
BASIC compiles the program currently in memory but does not create an OBJ file. 
You can abbreviate all positive COMPILE qualifiers to the first three letters of the qualifier 


keyword. A negative qualifier can be abbreviated to NO and the first three letters of the 
qualifier keyword. 


There must be a program in memory or the COMPILE command does not execute and 
BASIC does not signal an error or warning. 


General Rules 


ie 


If an object file for the program already exists in your directory, BASIC—PLUS—2 on RSTS/E 
systems overwrites it with the new object file. VAX—11 BASIC and BASIC—PLUS—2 on 
RSX—11M/M-—PLUS systems create a new version of the OB} file. 
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2. You should not specify both a file name and file type. For example: 
COMPILE NEWOBJ.FIL/LIS/OBJ 


© VAX-11 BASIC creates two versions of NEWOBJ.FIL. The first version, NEWOBJ.FIL:1, is 


the listing file; the second version, NEWOB)J.FIL;2, is the object file. If you specify only a 
file name, BASIC uses the OBJ and LIS file type defaults when creating these files. 


e BASIC—PLUS—2 creates only the object file and names it NEWOB}.FIL. 


3. Use the COMPILE/NOOBJECT command to check your program for errors without pro- 
ducing an object file. 


Examples 


COMPILE NEWSTRING/DOUBLE /LIST 
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7.0 CONTINUE 


s Ww a a a ww 


Function 
The CONTINUE command continues program execution after BASIC executes a STOP statement or, 
in VAX—11 BASIC, encounters a CTRL/C. 


Format 


| CONTINUE | 


ee 


Syntax Rules 


None. 


General Rules 


1. In VAX-11 BASIC, a program stops executing in response to a STOP statement or a 
CTRL/C: 


e You can enter immediate mode commands and resume program execution with the 
CONTINUE command. 


e You cannot resume program execution if you have made source code changes or 
additions. 


2. In BASIC—PLUS-2, a program stops executing when BASIC executes a STOP statement and 
control passes to the BASIC—PLUS—2 debugger, which prompts with a pound sign (#). 
Type the CONTINUE command to resume program execution. Note that if the program 
was executed with the RUN/DEBUG command, you can enter debugger commands be- 
fore resuming program execution with the CONTINUE command. See Part VI in this 
manual for more information on debugger commands. 

Examples 


VAX—11 BASIC 


42BAS-1I-STO; Stop 
-BAS-I-FROLINNOD; from line 275 in module ABC 
Ready 


CONTINUE 


BASIC—PLUS—2 


Stop at line 20 


#CONTINUE 


BASIC Reference Manual 53 


DELETE 


8.0 DELETE 


Function 


The DELETE command removes a specified line or range of lines from the program currently in 


memory. 


Format 


DELETE lin-num [ sep lin-num ] ,... 


Syntax Rules 


1. 


You must enter at least one line number. If you do not, DELETE has no effect in VAX—11 
BASIC, while BASIC—PLUS-—2 signals the error ‘Illegal Delete command”. 


The sep characters allow you to delete individual lines or a block of lines. 


e If you separate line numbers with commas, BASIC deletes each specified line number. 


e If you separate line numbers with a hyphen (-), BASIC deletes the inclusive range of 
lines. The lower line number must come first. If it does not, DELETE has no effect in 
VAX—11 BASIC, while BASIC—PLUS-2 signals the error ‘‘Bad line number pair’’. 


You can combine individual line numbers and line ranges in a single DELETE command. 
Note, however, that a line number range must be followed by a comma and not another 
hyphen, or BASIC signals an error. 


General Rules 


1, 


Examples 


BASIC—PLUS-—2 signals an error if there are no lines in the specified range. VAX—11 BASIC 
does not signal an error and the DELETE command has no effect. 


If you do not specify a beginning line number for a range, VAX—17 BASIC signals the error 
“illegal line number’. BASIC-PLUS—2 assumes a beginning line number of 1 and deletes 
all lines in the range 1 — lin-num. 


If you do not specify an end line number in a range, VAX—11 BASIC does not delete any 
lines and does not signal an error. BASIC—PLUS—2 deletes only the specified line number. 


DELETE 30 


DELETE 70-80, 110, 124 


DELETE 30+60+90-110 
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Function 


The DSKLIB command lets you select a disk-resident, object module library to be used when you 
build your program. When you use the BUILD command, BASIC—PLUS—2 includes the specified 
library in the Task Builder command file. Every system has a disk library default set when 
BASIC—PLUS-2 is installed. 


Format 


[a | 


| DSKLIB [ file-spec ] | 


Syntax Rules 


1. If you enter the DSKLIB command without a file-spec, BASIC-PLUS—2 prompts for one and 
displays the name of the current default disk-resident library. 


e File-spec can be a disk-resident, object module library supplied with BASIC—PLUS—2 or a 
user-created library. 


e If you type a carriage return in response to the prompt, BASIC—PLUS—2 uses the default 
disk-resident library. 


General Rules 


1. The object module libraries supplied by BASIC—PLUS—2 are LB:BP2OTS.OLB on RSTS/E 
systems and LB:[1,1]BP2OTS.OLB on RSX—11M/M-—PLUS systems. LB: is a RSTS/E logical 
name for the library account on disk. These libraries contain the BASIC Object Time 
System (OTS). OLB is the default object module library file type. If your system does not 
have memory-resident libraries, the Task Builder extracts all BASIC routines from these 
disk-resident libraries. See BASIC on RSX-11M/M-—PLUS Systems and BASIC on RSTS/E 
Systems for more information on object module libraries. 


2. The Task Builder links the specified library to your program when you task-build the 
program. You must use the DSKLIB command before you use the BUILD command to 
include the library you want in the Task Builder command file. 


3. The DSKLIB library you specify is included in all Task Builder command files until you 
specify a new library with the DSKLIB command or exit from the BASIC environment. 
When you exit from the BASIC environment, the default object module library set at 
installation is restored as the default disk-resident library. 


4. You can override the DSKLIB command with the /DSKLIB qualifier added to the BUILD 
command, but the specified library remains in effect for only one BUILD routine. 


5. The Task Builder returns an error message when the requested disk-resident library is not 
available. 


6. Consult your system manager for information about the disk-resident libraries available to 
you. 
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Examples 
RSX—11M/M-—PLUS Systems 


DSKLIB LB:fi+1]BP20TS 


RSTS/E Systems 


DSKLIB LB:6P20TS 
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10.0 EDIT 


Function 


The EDIT command allows you to edit individual program lines in the BASIC environment. In 
VAX—11 BASIC, EDIT with no arguments invokes the default text editor and reads the current program 
into the editor’s buffer. In BASIC-PLUS—2, EDIT with no arguments puts you in the BASIC—PLUS—2 
editing mode. BASIC—PLUS—2 editing mode commands are listed in Table 14 and described in 
Sections 10.1 to 10.6. 


Format 


VAX-11 BASIC 


EDIT [ [ lin-num ] search-clause [ replace-clause ] ] 


search-clause: delim una-str1 delim 
replace-clause: [ unq-str2 ] [ delim [ int-const1 ] [ , int-const2 ] ] 


BASIC-PLUS-2 


EDIT [ [ lin-num [ —lin-num ] ] search-clause [ replace-clause ] ] 


search-clause: delim unq-sir1 delim 


replace-clause: _[ unq-str2 ] delim [ int-const1 ] 


Syntax Rules 
1. Lin-num specifies the line to be edited. 


2. Search-clause specifies the text you want to remove or replace. Ung-str1 is the search 
string you want to remove or replace. 


3. Replace-clause specifies the replacement text and the occurrence of the search string you 
want to replace. 


e Ung-str2 is the replacement string. 


e Int-const1 specifies the occurrence of unq-str! you want to replace. If you do not specify 
an occurrence, BASIC replaces the first occurrence of unq-str1. 


4. Delim can be any printing character not used in ung-str1 or ung-str2. The examples in this 
and the following sections use the slash (/) as a delimiter. 


5. The delim characters in search-clause must match, or BASIC signals an error. 


6. If the delim you use to signal the end of replace-clause does not match the delim used in 
search-clause, BASIC does not signal an error and treats the end delim as part of unq-str2. 
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BASIC replaces or removes text in a program line as follows: 
e If ung-str1 is found, BASIC replaces it with ungq-str2. 
e If ung-str1 is not found, BASIC signals an error. 


e If ung-str? is null, VAX—711 BASIC signals ‘‘no change made’’. BASIC—PLUS—2 replaces 
the first character of the last edited line with ung-str2 and does not signal an error. 


e If ung-str2 is null, BASIC deletes unq-str1. The delim in the replace-clause is required if 
you want to delete unq-str1. 


e BASIC matches and replaces strings exactly as you type them. If ung-str7 is uppercase, 
BASIC searches for an uppercase string. If it is lowercase, BASIC searches for a lowercase 
string. 


VAX-11 BASIC 
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The EDIT command followed by a carriage return causes BASIC to temporarily save your 
program in a file called BASEDITMP.TMP. BASIC then invokes the same editor you use 
when you type the DCL EDIT command. When you finish editing your program and 
exit the editor, the edited program is the program currently in memory, and the context 
of the BASIC environment is unchanged. Note that BASIC deletes all versions of 
BASEDITMP.TMP when you return to BASIC from the editor. 


Int-const2 in replace-clause specifies the sub-line of a block of program code where you 
want BASIC to begin the search. 


BASIC—PLUS—2 


le 


The EDIT command followed by a carriage return puts you in the BASIC—PLUS—2 editing 
mode. Editing mode commands, listed in Table 14 and described in Sections 10.1 to 10.6, 
are valid only in the BASIC_PLUS—2 editing mode. The editing mode prompt is an asterisk 
(*). 


BASIC—PLUS-2 sets a specified line number as the current edit line, even when the editing 
operation fails. That line number remains set as the current edit line until you specify 
another line number or exit the BASIC environment. 


You can edit a range of lines by separating two line numbers with a hyphen. BASIC signals 
an error and does not edit the specified range if there are spaces between the hyphen and 
the line numbers. 


If you specify a range of lines and an occurrence, BASIC replaces each occurrence of 
ung-str? in each line of the range beginning with the specified occurrence. For example: 


10 PRINT DISPLAYS» DISPLAYS»s» DISPLAYS 
20 PRINT DISPLAY$+ DISPLAYS+s DISPLAY$ 
EDIT 10-20 /DISPLAY# /NEWS /2 


10 PRINT DISPLAYS: NEWS: NEWS 
20 PRINT DISPLAYS,» NEWS; NEWS 


"DISPLAYS" replaced by "NEWS", 
4 substitutions 
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General Rules 
VAX—11 BASIC 


1; 


2. 


VAX—11 BASIC displays the edited line with changes after the EDIT command successfully 
executes. 


If you specify a /in-num with no text parameters, VAX—11 BASIC displays the line. 


BASIC—PLUS—2 


1. 


Examples 


BASIC-PLUS-2 displays the edited line or lines with changes after the EDIT command 


successfully executes. It also displays a message showing the search string, replacement 
string, and number of replacements made. 
If you want to edit a range of numbers, you must specify both the beginning and end of the 


range. BASIC—PLUS—2 does not default to the last edited line or to the last line number in 
the program. 


When you specify a:lin-num with no text parameters, BASIC—PLUS—2 displays the message 
“Current edit line is x’’, where x is the specified lin-num. 


When you type EDIT with no parameters to enter the editing mode, BASIC—PLUS—2 checks 
the last edited line number to make sure that it still exists in the current program. If it has 
been deleted, BASIC-PLUS—2 displays the message ‘‘?No current line’. 


VAX—11 BASIC 


EDIT 100 /LEFT#/RIGHT#/3:+2 


EDIT 


BASIC—PLUS—2 


EDIT 300-400 /LEFTS/ / 


EDIT 300 /LEFT#/RIGHTS/3 


EDIT 
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Table 14: BASIC-PLUS—2 Editing Mode Commands 


DEFINE 


EXECUTE 

EXIT (or CTRL/Z) 
FIND 

INSERT 


SUBSTITUTE 


Used to enter a macro definition. A macro definition consists of editing commands. You cannot, 
though, use the DEFINE and EXECUTE commands in a macro definition. To end the macro 
definition, type a carriage return and then EXIT or CTRL/Z. You must use the EXECUTE command 
to execute the macro definition. 


Executes the macro defined by the DEFINE command as many times as you specify. 


Allows you to exit from editing mode, execute an INSERT command, or end a DEFINE command. 
Searches from the last edited line to the end of the current program for a specified string. 


Allows you to add program lines after a specified line number. Type a carriage return and EXIT or 
CTRL/Z to execute this subcommand. 


Performs the same function and accepts the same text parameters as the EDIT command; you 
cannot, however, specify line numbers or line number ranges. 
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10.1 DEFINE (BASIC—PLUS—2) 


Function 


The DEFINE editing mode command allows you to enter a macro definition. The macro consists of a 
series of editing mode commands in the order in which they are to execute. 


Format 


f jo | | 
| ( DEFINE | | 


Syntax Rules 


1. The macro definition must consist of valid editing mode commands or BASIC—PLUS—2 
signals an error. You cannot use the DEFINE or EXECUTE editing mode commands in a 
macro definition. 


General Rules 


1. Type the DEFINE command and a carriage return, then enter your macro definition. Type 
EXIT or CTRL/Z in response to the DEFINE prompt (—>) when you have finished entering 
your macro definition. BASIC—PLUS-—2 displays the editing mode prompt, and you can 
enter more editing commands. . 


2. BASIC writes the macro definition to a file, so the definition remains in effect until you 
enter another DEFINE command. That is, an EXECUTE command executes the last defined 
macro definition. 


Examples 


#DEFINE 


Enter command sequence: 
->FIND REM 

->SUBSTITUTE /REM/!/ 

- 2EXIT 
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10.2 EXECUTE (BASIC-PLUS-2) 


Function 


The EXECUTE editing mode command executes the last macro defined by the DEFINE command. You 
specify the number of times the macro is to execute. 


Format 


EXE 


EXECUTE [ int-const ] 


Syntax Rules 


1. Int-const specifies the number of times the macro executes. If you do not specify int-const, 
BASIC—PLUS—2 executes the macro once. 


General Rules 


1. An EXECUTE command always executes the last defined macro definition. If no macro 
definition exists, BASIC—PLUS—2 signals the error ‘‘Command sequence has not been 
defined’’. 

Examples 


*EXECUTE 5 
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10.3 EXIT or CTRL/Z (BASIC—PLUS—2) 
Function 


The EXIT or CTRL/Z editing mode command marks the end of a DEFINE or INSERT command or exits 
from editing mode. 


Format 


| jE | | 
| | EXIT | | 


Syntax Rules 


None. 


General Rules 


1. If you type EXIT or CTRL/Z in response to the editing mode prompt, BASIC—PLUS—2 exits 
from editing mode. 


2. If you type EXIT or CTRL/Z to end a DEFINE or INSERT command, BASIC-PLUS—2 dis- 
plays the editing mode prompt and you can enter more editing commands. 


Examples 


*DEFINE 


Enter command sequence 
->FIND REM 


->SUBS /REM/! 


=~ FF ta 


- EXIT 
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10.4 FIND (BASIC-PLUS-2) 


Function 


The FIND editing mode command searches the current program for a specified string starting at the 
last edited line and continuing to the end of the program. 


Format 


F 


FIND [ uno-str ] 


Syntax Rules 


1. The FIND command does not require character delimiters for ung-str. Delimiters are the 
space after the command and a carriage return. 


General Rules 


1. When ung-str is found, BASIC-PLUS-—2 displays the line that contains the ung-str, sets it as 
the last edited line, and displays an informational message. 


2. If unq-str is not found, the last edited line remains unchanged and BASIC—PLUS—2 displays 
a message telling you that the string was not found. 


3. The FIND command matches unq-str exactly as you type it. If ung-str is uppercase, 
BASIC—PLUS—2 searches for uppercase characters. The delimiters (space and carriage 
return) are not included in the match. 


4. If you do not specify an unq-str, the FIND command matches the unq-str specified by the 
last FIND command. If there is no previous FIND command, BASIC—PLUS—2 matches the 
first character of the last edited line. 


Examples 


*FIND PRIMT 
330 PRIMT ‘How many receipts do you have’ sRECEIPTS 


"PRIMT" found on line 330 
+ 
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10.5 INSERT (BASIC—PLUS—2) 


Function 


The INSERT editing mode command allows you to add lines to a program. 


Format 


I 
INSERT 


a es 


[ lin-num } 


Syntax Rules 


1. Lin-num specifies the line number after which you want to insert new program lines. If you 
do not specify a lin-num, BASIC defaults to the last edited line. 


2. If lin-num does not exist in the source program currently in memory, BASIC signals an 
error. 


General Rules 


1. Type in program lines, beginning with a line number, after entering the INSERT command. 
When you are finished inserting lines, type EXIT or CTRL/Z to return to the editing mode. 
BASIC—PLUS—2 displays the editing mode prompt and you can enter more editing 
mode commands. 


2. If you insert a line number that already exists, BASIC—PLUS—2 replaces the existing line 
with the code you insert and does not signal a warning. 


3. BASIC—PLUS-—2 does not perform syntax checks on inserted program lines even when 
syntax checking is enabled. 


4. The current edit line does not change. For example, if the current edit line is 10 and you 
insert lines 20 and 30, line 10 remains the current edit line. 


Examples 


#INSERT 30 


Enter lines to be added after line 30 
-?40 INPUT ‘More receipts’ :RECEIPTSS 
-?30 IF RECEIPTS$ = "" 

-> THEN GOTO 32767 
-> END IF 

- EXIT 

# 
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10.6 SUBSTITUTE (BASIC-PLUS-2) 


Function 


The SUBSTITUTE editing mode command allows you to substitute one character string for another in 
the program currently in memory. SUBSTITUTE is the editing mode equivalent of the EDIT command 
with one exception: you cannot specify a range of lines. The SUBSTITUTE subcommand can replace 
only one occurrence of the specified search string, while the EDIT command can replace all occur- 
rences in a range of lines, if you so specify. 


Format 


Ss 
SUBSTITUTE } search-clause [ replace-clause ] 


search-clause: delim unq-str1 delim 
replace-clause: [ unq-str2 ] delim [ int-const ] 


Syntax Rules 


1. Delim marks the beginning and end of the search and replace strings. Delimiters are 
required before and after unq-str1. The delimiter after ung-str2 is optional. 


e Delim can be any printing character not used in the search or replace strings. The 
examples in this section use the slash (/) as a delimiter. 


e The beginning and ending delim characters must match, or BASIC signals an error. 


2. Ung-str1 specifies the string you want to remove or replace. Unq-str2 specifies the string to 
be substituted for unq-str1. 


e If unq-str1 is found, BASIC replaces it with unq-str2. 
e If unq-str1 is not found, BASIC signals an error. 
e If you do not specify unq-str2, BASIC deletes unq-str7. 


e If you do not specify unq-str?, BASIC replaces the first character of the last edited line 
with ung-str2. 


e The SUBSTITUTE subcommand matches and replaces strings exactly as you type them. If 
unq-str1 is uppercase, BASIC searches for an uppercase string. If it is lowercase, BASIC 
searches for a lowercase string. 


3.  Int-const specifies the occurrence of str-lit! you want to replace. If you do not specify an 
int-const, BASIC replaces the first occurrence of str-lit?. 


4. If you type only the SUBSTITUTE subcommand and a carriage return, BASIC—PLUS—2 
signals the error ‘‘Parameters required”’. 
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1. BASIC displays the edited line with changes after the SUBSTITUTE command executes. 
Examples 


*SUBSTITUTE /AZ/ABSOLUTEZ/3 
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11.0 EXIT 
Function . 
The EXIT command or CTRL/Z clears memory and returns control to the operating system. 


Format 


EXIT 


Syntax Rules 
None. 
General Rules 


1. If you type EXIT after creating a new program or editing an old program without first typing 
SAVE or REPLACE, BASIC signals ‘“‘Unsaved change has been made, CTRL/Z or EXIT to 
exit’’. The message warns you that the new or revised program will be lost if you do not 
SAVE or REPLACE it. If you type EXIT again, BASIC exits from the environment whether 
you have saved your changes or not. 


Examples 


EXIT 
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Function 


The HELP command displays on-line documentation for BASIC commands, keywords, statements, 
functions, and conventions. 


Format 


| HELP [ unq-str ] ... | 


a | 


Syntax Rules 


1. If you type HELP with no parameters, BASIC displays a list of topics. 
2. Ung-str is BASIC topic, keyword, command, statement, function, or convention. 


3. The first unq-str must be a topic. If it is not, BASIC displays a list of topics for you to choose 
from. 


4. You can specify a subtopic after the topic. Separate one unq-str from another with a space. 


5. You can use the asterisk (*) wildcard character in unq-str or alone as ung-sir. If you use an 
asterisk in unq-str, BASIC displays information on all topics that match the specified por- 
tion of ung-str. If you use the asterisk alone, BASIC displays information on all BASIC 
topics. 


General Rules 


1. If the ung-str you specify is not a unique topic or subtopic, BASIC displays a information on 
all topics or subtopics beginning with ung-str. For example: 


Ready 
HELP STATEMENTS CH 


STATEMENTS 
CHAIN 

The CHAIN statement transfers control fromthe current Programto another 
BASIC Frogram. The Program to which you CHAIN must be in executable 
format, 

Format 

CHAIN <str-exep> 

Example 


240 CHAIN "COSINE.EXE" 
(continued on next page) 
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STATEMENTS 
CHANGE 
The CHANGE statement: 1) converts a string of characters to their ASCII 
integer values» or 2) converts a list of numbers to a string of ASCII 
characters, 
Format 
String Variable to Array: 
CHANGE str-exPp TO num-array 
Array to String Variable: 
CHANGE num-array TO str-vbl 
Example 
200 CHANGE ARRAY_CHANGES TO A$ 
Topic? 


2. An asterisk (*) indicates that you want to display information that matches any portion of 
the topic you specify. For example, if you type HELP GO*, BASIC displays information on 
GOSUB and GOTO. 


3. When information on a particular topic or subtopic is not available, BASIC signals the 
message “Sorry, no documentation on unq-str’’ and a list of ‘Additional information 
available’’. 


Examples 


HELP STATEMENTS ON GOTO 
STATEMENTS 
ON 
GOTO 


The ON GOTO statement transfers Program control to one of several lines» 
depending on the value of a control expression: 


Format 


{ GO TO } 
ON int-exp { GOTO +} target +++ € OTHERWISE target J] 


Example 
3390 ON INDEX% GOTO 700;800;900; OTHERWISE 1000 


Topic? 
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13.0 IDENTIFY 


Function 


The IDENTIFY command displays an identification header on the controlling terminal. The header 
contains the name and version number of BASIC. 


Format 


| IDENTIFY | 


| ee | 


General Rules 


1. The message displayed by the IDENTIFY command includes the name of the BASIC com- 
piler and the version number. 


Examples 
VAX—11 BASIC 


IDENTIFY 


VAX-11 BASIC V2.0 


BASIC—PLUS—2 


IDENTIFY 


PDP-11 BASIC-PLUS-2 V2.0 
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14.0 INQUIRE 


Function 


The INQUIRE command is a synonym for the HELP command. See the HELP command for syntax 
rules. 
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15.0 LIBRARY (BASIC—PLUS—2) 


Function 


The LIBRARY command allows you to specify a memory-resident BASIC—PLUS—2 or user-created 
library to be used when you task-build the program. When you use the BUILD command, 
BASIC—PLUS-—2 includes the specified library in the Task Builder command file. The default library for 
the LIBRARY command is chosen by your system manager when BASIC—PLUS-—2 is installed. 


Format 


oo. ee ee eg rte ee ee 


LIBRARY [ lib-param ] 


lib-param: file-spec 


lib-nam 
NONE 


Syntax Rules 


1. If you enter the LIBRARY command without a /ib-param, BASIC-PLUS—2 prompts for one and 
displays the name of the current default memory-resident library. 


e Lib-nam or file-spec can be a memory-resident library supplied by BASIC—PLUS—2 or a user- 
created library. If you specify only lib-nam with no device, BASIC-PLUS—2 assumes LB: on 
RSTS/E systems and LB:[1,1] on RSX—-11M/M-PLUS systems. 


@ NONE tells the Task Builder not to link your task to the BASIC default memory-resident 
library. Therefore, the Task Builder links to the BASIC disk-resident, object module 
library, BP2OTS.OLB. 


* If you type a Carriage return in response to the prompt, the current default memory-resident 
library is used. 


General Rules 


1. The memory-resident libraries supplied by BASIC—PLUS—2 are BP2RES and BP2SML. 
Because memory-resident libraries are optional, your system manager can select none, 
one, or both then BASIC—PLUS-—2 is installed. See BASIC on RSX—11M/MPLUS Systems or 
BASIC on RSTS/E Systems for information on using BASIC—PLUS—2 memory-resident librar- 
ies. See your system manager for information on the libraries available on your system. 


2. On RSTS/E systems, the LIBRARY command does not require the LB: logical name. BASIC 
automatically searches this account for the memory-resident library symbol] table. On 
RSX-11M/M-PLUS systems, the LIBRARY command automatically references libraries on 
LB:[1,1] unless you specify another UIC. 


3. BASIC—PLUS-2 links the specified library to your program when you task-build the pro- 
gram. You must use the LIBRARY command before you use the BUILD command to 
include the specified library in the Task Builder command file. 
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Examples 


The library you specify is included in your Task Builder command files until you specify a 
new library with the LIBRARY command or exit from the compiler. When you exit from the 
compiler, the original default library is restored as the default. 


LoS See he eweviwiwvrwu | um wu 


You can override the LIBRARY command with the /LIBRARY qualifier added to the BUILD 
command, but the specified library remains in effect for only one BUILD routine. 


The Task Builder returns an error message when the requested resident library is not 
available. 


LIBRARY BP2RES 
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16.0 LIST and LISTNH 


Function 


The LIST command displays the program lines of the program currently in memory. Line numbers are 
sequenced in ascending order. LISTNH displays program lines without the program header. 


Format 


VAX-11 BASIC 


rer 


LISTNH 
[ lin-num [ sep [ lin-num J ] ] ... 


LIST 


BASIC—PLUS—2 


LISTNH 
LIST { [ —] lin-num ] [ sep [ lin-num ] ]... 


Syntax Rules 
1. The LIST command displays program lines, along with a header containing the program 
mama tha rurrant tima and tha Anata Tran ciuinnerace tha nenagram khacdtar fens! ISTNH 
HaQHIte, UIC CULPCHIL UFTIO, Qiu UIE UAL. TU SUpPpITsS UIC PIUSI allt MCaAUTI, LYM LIOTINIT. 


2. LIST without parameters displays the entire program. 


3. The sep characters allow you to display single lines or a range of lines. 


e To display single lines, separate line numbers with commas. For example: 


LIST 30:70 
displays a header and lines 30 and 70. 


© To display an inclusive range of lines, separate line numbers with a hyphen. The first 
number must be lower than the second number in the range or BASIC signals an error. 
- For example: 


LIST 30-70 
displays lines 30 through 70. 


4. Line number ranges must be separated from other ranges or individual line numbers by 
commas as BASIC does not allow two consecutive hyphens. 


BASIC Reference Manual 75 


LIST 


VAX-11 BASIC 


1 
I. 


A lin-num followed by a hyphen and a carriage return displays the specified line and ail 
remaining lines in the program. 


A hyphen between the LIST command and /in-num causes VAX—11 BASIC to signal an 
error. 


BASIC—PLUS—2 


il 


3: 


A hyphen between the LIST command and the /in-num displays all lines from the begin- 
ning of the program up to and including the lin-num you specify. 


A lin-num followed by a comma or a hyphen and a carriage return displays only the 
specified line. 


If there are no lines in the specified range, BASIC—PLUS—2 signals an error. 


General Rules 


1. 


Examples 


BASIC displays the source program lines in the order you specify in the command line. 
That is, BASIC displays line 100 before line 10 if you type LIST 100,10. 


VAX-11 BASIC 


LIST 50% 


200-300, 30000- 


BASIC—PLUS—2 


LISTNH -30, 2000-2500, 19000 
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17.0 LOAD 


Function 


The LOAD command makes a previously created object module or modules available for execution 
with the RUN command. 


Format 


LOAD file-spec [ + file-spec ] ... 


Syntax Rules 


1. File-spec must be a BASIC object module or BASIC signals an error. OBJ is the default file 
type. If you specify only the file name, BASIC searches for an OBJ file in the current default 
directory. 


2. Each device and directory specification applies to all following file specifications until you 
specify a new directory or device. 


3. Each new LOAD command cancels the effect of a previous LOAD command. That is, the 
LOAD command clears all previously loaded object modules from memory. 


4. The LOAD command accepts multiple device, directory, and file specifications. 


General Rules 


1. BASIC does not process the loaded object files until you issue the RUN command. Conse- 
quently, errors in the loaded modules may not be detected until you execute them. 


2. BASIC signals an error: 
e If the file is not found 
e If the file specification is not valid 
e If the file is not a BASIC object module 
e |f run-time memory is exceeded 
Errors do not change the program currently in memory. 


3. Typing the LOAD command does not change the program currently in memory. 
Examples 


LOAD PROGA + PROGB + PROGC 
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The LOCK command changes default values for COMPILE command qualifiers. It is a synonym for 
the SET command. See the SET command for syntax rules. 
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NEW 


Function 


The NEW command clears BASIC memory and allows you to assign a name to a new program. 


Format 


NEW [ prog-nam ] 


Syntax Rules 


1.  Prog-nam is the name of the program you want to create. VAX-11 BASIC and 
BASIC—PLUS—2 on RSX—11M/M-—PLUS systems allow names to contain up to nine alpha- 
numeric characters. BASIC-PLUS—2 on RSTS/E systems allows names to contain up to six 
alphanumeric characters. 


2. BASIC—PLUS—2 on RSTS/E systems truncates a prog-nam that exceeds six characters and 
does not signal an error. 


3. VAX-11 BASIC and BASIC—PLUS—2 on RSX-11M/M-PLUS systems signal an error if the 
prog-nam exceeds nine characters. 


4. VAX-11 BASIC signals ‘error in program name” if you specify a file type. BAS/C—PLUS—2 
ignores the file type and does not signal an error. 


General Rules 


1. If you do not specify a prog-nam, BASIC prompts with: 


New file name-- 


© 
c 
@ 


2. The defauit name is NONAME. if you do not provide a prog-nam in response t 
prompt, BASIC assigns the file name NONAME to your program. 


3. When you type the NEW command, the program currently in memory is lost. Program 
modules loaded with the LOAD command remain unchanged. 


Examples 


NEW PROG1 
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20.0 ODLRMS (BASIC—-PLUS-2) 


Function 


The ODLRMS command allows you to select an overlay description (ODL) file to describe the RMS 
overlay structure to be used when your program is task built. When you use the BUILD command, 
BASIC—PLUS—2 includes the specified ODL file in the Task Builder command file. Every system has 
an ODL default set when BASIC—PLUS-—2 is installed. See your system manager for the name of your 
BASIC default. 


Format 


ODLRMS [ odl-param ] 


odl-param: file-spec 
NONE 


Syntax Rules 


1. If you enter the ODLRMS command without an od/-param, BASIC—~PLUS—2 prompts for 
one and displays the name of the current default ODL file. 


e File-spec can be an ODL file supplied by RMS or a user-created file. Table 15 lists and 
describes RMS ODL files. 


e NONE tells the Task Builder not to link your task to any RMS ODL file. 


e If you type a carriage return in response to the prompt, BASIC—PLUS—2 uses the default 
ODL file. 


General Rules 


1. New versions of RMS can change ODL file names, so consult the RMS distribution kit for 
current ODL names. LB: is a RSTS/E logical name for the library account on disk. On 
RSX—11M/M-—PLUS systems, you must specify LB:[1,1] before the ODL file name. 


2. €nter the ODLRMS command before you enter the BUILD command. The ODL file you 
specify is included in all Task Builder command files until you enter a new ODLRMS 
command or exit from the BASIC environment, at which time BAS/C—PLUS-—2 returns to the 
ODL default file. 


3. You can override the ODLRMS command with the ODL qualifier to the BUILD command 
for a single BUILD operation. 


4. Refer to the RMSRES compiler command to see which ODL files are required for each RMS 
library. 
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ODLRMS 


an 


The Task Builder returns an error message if the ODL file you select is not available or 
valid. Consult your system manager for information about ODL files available to you. 


6. Consult BASIC on RSX-—11M/M-—PLUS Systems or BASIC on RSTS/E Systems for more 
information on using RMS libraries. 


Table 15: ODL Files 


ODLRMS File Organization Type of Overlay 


Option Library Segments 
RMSRLX Yes Yes Yes Memory None 
DAPRLX Yes Yes Yes Memory None 
RMS11S Yes Yes No Disk 11 
RMS12S_ | Yes | Yes | No Disk 5 
RMS11X Yes Yes Yes Disk 35 
RMS12X Yes Yes Yes Disk 13 
DAP11X Yes Yes Yes Disk 16 
Examples 


RSX—11M/M-—PLUS Systems 


ODLRMS LB:C1i;+iIRMSRLX.ODL 


RSTS/E Systems 


ODLRMS LB:RMSRLX.ODL 
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21.0 OLD 
Function 
The OLD command brings a previously created BASIC program into memory. 


Format 


OLD [ file-spec ] 


Syntax Rules 


1. If you do not name a file-spec, BASIC prompts for one. If you do not enter a file-spec in 
response to the prompt, BASIC searches for a file named NONAME.BAS (VAX—17 BASIC) 
or NONAME.B2S (BASIC—PLUS—2) in the current default directory. 


2. The default file type is BAS for VAX—11 BASIC and B2S for BASIC~PLUS-2. 


General Rules 


1. If the compiler cannot find the file-spec, VAX—-11 BASIC signals the error “file not found” 
and BASIC—PLUS-—2 signals ‘‘can’t find file or account’. 


2. When the specified file is found, it is placed in memory and any program currently in 
memory is erased. If BASIC does not find the specified file, the program currently in 
memory does not change. 


3. If you specify a file that does not begin with a line number, BASIC discards all text up to the 
first line number, brings the file into memory, and signals the error ‘“‘“Non-continued state- 
ment has no line number near <line number>’’. You can then LIST and SAVE the 
program. 


Examples 


OLD CHECK 
Ready 
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22.0 Qualifiers 


Function 


BASIC qualifiers allow you to specify defaults for the compilation process and the BASIC environ- 
ment. You specify qualifiers with the COMPILE and SET commands. In BASIC-PLUS—2, you can also 
specify qualifiers with the BUILD and RUN commands. 


Format 


Syntax Rules 


1. The slash delimiter is not required before the first qualifier in the SET command. Multiple 
qualifiers, however, must be separated by slashes or commas. See the syntax rules for the 
SET command for more information on separating qualifiers. 


2. You can abbreviate all positive qualifiers to the first three letters of the qualifier keyword. 
You can abbreviate a negative qualifier to NO and the first three letters of the qualifier 
keyword. 


General Rules 


1. Table 16 lists VAX—11 BASIC qualifiers and their functions. Table 17 lists BASIC—PLUS—2 
qualifiers, the commands they can be used with, and their functions. 


2. In cases of ambiguous or erroneous qualifiers, VAX—11 BASIC signals the error ‘‘Unknown 
qualifier’, while BASIC—PLUS-—2 signals “Illegal switch’. 


3. When you exit from the BASIC environment, all defaults set with qualifiers return to the 
defauits. Use the SHOW command before setting any qualifiers to dispiay your system 
defaults. 


Examples 


COMPILE /NOOBJ / DOUBLE / DEBUG 


SET /TYPE_DEFAULT: EXPLICIT /LIST 
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Table 16: VAX—11 BASIC COMPILE and SET Command Qualifiers 


[NOJANSI_STANDARD 


Tells BASIC to compile programs according to the ANSI Minimal 
BASIC Standard and to flag syntax that does not conform to the 
standard. See BASIC on VAX/VMS Systems for information on 
the ANSI Minimal BASIC Standard. 


[NOJAUDIT [ sep text-entry | 


Tells BASIC to include a history entry in the CDD data base when 
a CDD definition is extracted. Str-lit is a quoted string. File-spec 
is a text file. The history entry includes: 


sep: 


@ The contents of str-lit, or up to the first 64 lines in the file 
specified by file-spec 


str-lit 
file-spec 


text-entry: 


ee 


¢ The name of the program module, process, user name, and 
user UIC that accessed the CDD 


© The time and date of the access 
e A note that access was made by the BASIC compiler 


e A note that the access was an extraction 


[NO]BOUNDS_CHECK Tells BASIC to perform range checks on array subscripts. BASIC 
checks that all subscript references are within the array bound- 


aries set when the array was declared. 


Causes the compiler to allocate eight bits of storage as the default 
for all integer data not explicitly typed in the program. Untyped 
integer values are treated as BYTE vaiues and must be in the 
BYTE range or BASIC signals the error ‘Integer error or over- 
flow’’. Table 2 in this manual lists BASIC data types and ranges. 


[NO]CROSS.__REFERENCE [ sep [NO]KEYWORDS ] | Causes the compiler to include cross-reference information in the 
program listing file. If you specify KEYWORDS, BASIC also 
cross-references BASIC keywords used in the program. The list- 
ing file takes the program name as the file name and a default file 


type of LIS. 


[NO]DEBUG Tells BASIC to provide records for the VAX—-11 Symbolic 
Debugger. See BASIC on VAX/VMS Systems for information on 


using the VAX—11 Symbolic Debugger. 


DECIMAL_SIZE sep (d,s) 


Allows you to specify the default size and precision for all 
DECIMAL data not explicitly assigned size and precision in the 
program. You specify the total number of digits (d) and the num- 
ber of digits to the right of the decimal point (s). BASIC signals 
the error “Decimal error or overflow’ (ERR=181) when 
DECIMAL values are outside the range specified with this quali- 
fier. See Table 2 in this manual and Appendix C in BASIC on 
VAX/VMS Systems for information on the storage and range of 
packed decimal data. 
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Table 16: VAX—11 BASIC COMPILE and SET Command Qualifiers (Cont.) 


ee 


DOUBLE 


Causes the compiler to allocate 64 bits of storage in 
D_FLOAT format as the default size for all floating-point 
data not explicitly typed in the program. Untyped floating- 
point values are treated as DOUBLE values and must be in 
the DOUBLE range or BASIC signals the error ‘Floating- 
point error or overflow’. Table 2 in this manual lists BASIC 
data types and ranges. 


[NOJFLAG [ sep ( flag-clause,... ) ] 


Causes BASIC to provide compile-time information about 
program elements that are not compatible with 
BASIC—PLUS—2 or that DIGITAL designates as declining. 
An element is designated declining when BASIC has a 
preferred and often more powerful way to perform the 
operation. 


i | : 


[NO]BP2COMPATIBILITY 
{[NO]DECLINING 


flag-clause: 


If you specify BP2COMPATIBILITY, BASIC will flag the 
following source code as incompatible with 
BASIC—PLUS-2: 


e String comparisons using (<),(>),(<=), or (>=) 
e DECIMAL keyword and DECIMAL function 

e@ HFLOAT keyword 

e GFLOAT keyword 

e LOC function 

e MAR and MAR% functions 

e MARGIN and NOMARGIN statements 

e RECORD declarations 


e More than 16 digits of precision in a floating-point literal 


e Explicit literal notation that specifies a radix 


e Explicit literal notation with data type other than “B”’ 
(BYTE), “W” (WORD), “’L’’ (LONG), ‘’S’’ (SINGLE), ““D’’ 
(DOUBLE), or “C’’ (CHARACTER) 


Names in the EXTERNAL statement that have more than 
six characters or contain characters not in the Radix-50 
character set 


BY DESC clauses on anything other than entire arrays or 
unsubscripted STRING variables 


BY VALUE clauses for anything other than BYTE or 
WORD unsubscripted variables 


More than eight parameters to a DEF, subprogram, or 
external function 


(continued on next page) 
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Table 16: VAX—11 BASIC COMPILE and SET Command Qualifiers (Cont.) 


GFLOAT 


HFLOAT 
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e Arrays of more than eight dimensions 


e Terminal-format files opened with no MAP or 
RECORDSIZE clause and no ACCESS READ clause 


e BY DESC, BY REF, and BY VALUE clauses in SUB and 
FUNCTION statements 


If you specify DECLINING, BASIC will flag the following 
source code as declining: 


e CVT$$ (use EDIT$) 


e CVT$%, CVT$F, CVT%$, CVTF$, and SWAP% (use 
multiple MAP statements) 


e DEF* functions (use DEF functions) 


e FIELD statements (use MAP DYNAMIC and REMAP) 


e GOTO lin-num% (do not use the integer suffix with a 
line number) 


Causes the compiler to allocate 64 bits of storage in 
G_FLOAT format as the default size for all floating-point 
data not explicitly typed in the program. Untyped floating- 
point values are treated as GFLOAT values and must be in 
the GFLOAT range or BASIC signals ‘Floating-point error | 
or overflow’’. Table 2 in this manual lists BASIC data types 
and ranges. 


Causes the compiler to allocate 128 bits of storage in 
H_FLOAT format as the default size for all floating-point 
data not explicitly typed in the program. Untyped floating- | 
point values are treated as HFLOAT values and must be in 
the HFLOAT range or BASIC signals ‘Floating-point error 
or overflow’’. Table 2 in this manual lists BASIC data types 
and ranges. 


Includes line number information in object modules. If you 
specify NOLINE in a program containing a RESUME state- 
ment or using the run-time ERL function, BASIC warns that 
the NOLINE qualifier has been overridden. 


Tells BASIC to produce a source listing file. By default, this 
file contains a memory allocation map. The listing file 
takes the name of the program and a default file type of 
LIS. 
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ST 


Causes the compiler to allocate 32 bits of storage as the 
default size for all integer data not explicitly typed in the 
program. Untyped integer values are treated as LONG val- 
ues and must be in the LONG range or BASIC signals the 
error “‘Integer error or overflow’. Table 2 in this manual 


Vict. 
lists BASIC data types and ranges. 


Causes BASIC to include the machine code generated by 
the compilation in the program listing file. 


Generates an object module with the same file name as the 
program and a default file type of OBJ. Use NOOBIJECT to 
check your program for errors without creating an object 
file. 


Table 16: VAX-11 BASIC COMPILE and SET Command Qualifiers (Cont.) 


[NO]MACHINE_CODE 


{NOJOBJECT 


[NO]JOVERFLOW | sep (data-type,...) ] Tells BASIC to report arithmetic overflow for operations on 


integer and/or packed decimal data. 


sep: 


INTEGER 
DECIMAL 


[NOJROUND Tells BASIC to round rather than truncate DECIMAL 
values. 


Tells BASIC to make calls to the Run-Time Library that set 
up the stack for BASIC variables, set up dynamic string and 
array descriptors, initialize variables, and enable BASIC 
error handling. ff you specify NOSETUP, BASIC will 
attempt to optimize your program by omitting these calls. 
If your program contains any of the following elements, 
BASIC provides an informational diagnostic and does not 
optimize your program: 


e CHANGE statements 


data-type: 


e DEF or DEF* statements 
e Dynamic string variables 
e Executable DIM statements 
e EXTERNAL string functions 
e MAT statements 
e MOVE statements for an entire array 


e ON ERROR statements 


(continued on next page) 
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Table 16: VAX—11 BASIC COMPILE and SET Command Qualifiers (Cont.) 


e READ statements 

e REMAP statements 

e RESUME statements 

e String concatenation 

e Built-in string functions 

e Virtual array declarations 

Note that program modules compiled with NOSETUP 
cannot perform any !/O and have no error handling capa- 
bilities. If an error occurs in such a module, the error is 
resignaled to the calling program. 


[NOJSHOW [ sep ( show-item,. Tells BASIC what to include in the listing file: 

; e CDD_DEFINITIONS specifies translated CDD defini- 

sep: . tions. 
e ENVIRONMENT specifies a listing of the compilation 

[NO]CDD_DEFINITIONS qualifiers in effect. 

[NOJENVIRONMENT e INCLUDE specifies a listing of the contents of %IN- 
show-item: [NOJINCLUDE CLUDE files. 

[NO]MAP fe 

[NO]OVERRIDE e MAP specifies a storage allocation map. 


: | 
e OVERRIDE canceis the effect of all %NOLIST directives 
in the source program. 


If you do not specify a show-item, BASIC uses the defaults 
set with the DCL command. 


Causes the compiler to allocate 32 bits of storage in 
F_FLOAT format as the default size for all floating-point 
data not explicitly typed in the program. Untyped floating- 
point values are treated as SINGLE values and must be in 
the SINGLE range or BASIC signals the error ‘‘Floating- 
point error or overflow’. Table 2 in this manual lists BASIC 
data types and ranges. 


SINGLE 


[NO]SYNTAX_CHECK Tells BASIC to perform syntax checking after each program 


line is typed. 


[NO]TRACEBACK Causes BASIC to include traceback information in the ob- 
ject file that allows reporting of the sequence of calls that 
transferred control to the statement where an error 


occured. 


(continued on next page) 
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Table 16: VAX—11 BASIC COMPILE and SET Command Qualifiers (Cont.) 


Sets the default data type (REAL, INTEGER, or DECIMAL) 
for all data not explicitly typed in your program or specifies 
that all data must be explicitly typed (EXPLICIT). 


e REAL specifies that all data not explicitly typed is float- 
ing-point data of the default size (SINGLE, DOUBLE, 

REAL GFLOAT, or HFLOAT). 
INTEGER 
DECIMAL 
EXPLICIT 


sep: 


default-clause: INTEGER specifies that all data not explicitly typed is 
integer data of the default size (BYTE, WORD, or 


LONG). 


DECIMAL specifies that all data not explicitly typed is | 
packed decimal data of the default size. 


EXPLICIT specifies that all data in a program must be 
explicitly typed. Implicitly declared variables cause 
BASIC to signal an error. 
VARIANT sep int-const Establishes int-const as a value to be used in compiler 
directives. The variant value can be referenced in a lexical 
sep: : expression by using the lexical function, %VARIANT. 
Int-const always has a data type of LONG. 


[NO]WARNINGS [ sep warn-clause ] Tells BASIC to display warning and/or informational mes- 

sages. If you specify WARNINGS but do not specify a 

sep: ; warn-clause, BASIC displays both warnings and informa- 
tional messages. 


{ 
[NO]JWARNINGS 


[NO]INFORMATIONALS 


warn-clause: | 


Causes the compiler to allocate 16 bits of storage as the 
default for all integer data not explicitly typed in the pro- 
gram. Untyped integer values are treated as WORD values 
and must be in the range —32768 to 32767 or BASIC sig- 
nals the error ‘Integer error or overflow.”” Table 2 in this 
manual lists BASIC data types and ranges. 
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Table 17: BASIC-PLUS—2 Command Qualifiers 
Qualifier 


Commands 


BRLRES: 


lib-param 


file-spec 


lib-param: NONE 


COMPILE 
RUN 
SET 


[NO]CHAIN COMPILE** 
RUN** 


SET** 


BUILD 
SET 
file-spec 


lib-param: NONE 


[NO]CROSS_REFERENCE|:[NO]KEYWORDS] COMPILE 


SET 
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Lets you specify a memory-resident library to be 
linked to your program. File-spec can be a library 
supplied with BASIC—PLUS—2 or a user-created 
library. NONE tells the Task Builder not to link 
your task to the default memory-resident library. 
See the BRLRES command syntax rules in this man- 
ual for more information on memory-resident 
libraries. 


Causes the compiler to allocate eight bits of storage 
as the default for all integer data not explicitly 
typed in the program. Untyped integer values are 
treated as BYTE values and must be in the BYTE 
range or BASIC signals the error ‘Integer error or 
overflow’. Table 2 in this manual lists BASIC data 
types and ranges. 


Enables other programs to CHAIN into the program 
using the LINE clause of the CHAIN statement. The 
default (CHAIN or NOCHAIN) is an installation 
option. If the program has more than 200 line 
numbers, NOCHAIN reduces the memory needs of 
the output program by disabling storage of line 
numbers in memory. You cannot chain from one 
DECNET node to another. 


Teils the Task Builder to cluster memory-resident 
libraries to increase the space available for your 
task. For the cluster qualifier to have an effect, at 
least two resident libraries must be linked to the 
task: the BASIC-PLUS—2 resident library, and one 
other resident library. File-spec specifies a mem- 
ory-resident library to be clustered. NONE speci- 
fies that only the BASIC-PLUS—2 and RMS libraries 
are clustered. 


if there is no default CLUSTER library, the 
CLUSTER qualifier without a parameter acts the 
same as the CLUSTER:NONE qualifier. The speci- 
fied library must be in the account LB: on RSTS/E 
systems or the account LB:[1,1] on RSX systems. 
Consult BASIC on RSX-11M/M-—PLUS Systems or 
BASIC on RSTS/E Systems for more information on 
using RMS libraries. 


Causes the compiler to include cross-reference 
information in the program listing file. If you spec- 
ify KEYWORDS, BASIC also cross-references 
BASIC keywords used in the program. The listing 
file takes the program name as the file name and a 
default file type of LST. 


(continued on next page) 
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[NO]DEBUG COMPILE 
RUN 
SET 


DOUBLE COMPILE 
RUN 
SET 


DSKLIB : file-spec 


[NO] DUMP 


EXTEND: int-const BUILD 


SET 


FLAG:([NO]DECLINING COMPILE 
RUN 
SET 
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Tells BASIC to provide records for the 
BASIC—PLUS—2 debugger when you compile a pro- 
gram or to pass control to the debugger when you 
execute a program with RUN in the BASIC envi- 
ronment. The LINE qualifier must be in effect when 


in effect. 


Causes the compiler to allocate 64 bits of storage 
as the default size for all floating-point data not 
explicitly typed in the program. Untyped floating- 
point values are treated as DOUBLE values and 
must be in the DOUBLE range or BASIC signals the 
error ‘Floating-point error’. Table 2 in this manual 
lists BASIC data types and ranges. 


lets you specify a disk-resident object module 
library to be linked to your program. File-spec can 
be a library supplied with BASIC—PLUS—2 or a 
user-created library. NONE tells the Task Builder 
not to link your task to the default object module 
library. See the DSKLIB command syntax rules for 
more information on disk-resident libraries. 


Tells the Task Builder to generate a memory dump 
if the program aborts with a fatal error. 


Specifies the amount of space to be added to the 
initial task size when the task is started. The Task 
Builder rounds the extension up to the nearest 
32—word boundary. The maximum extension is 
32000. 


Causes BASIC to provide compile-time information 
about program elements that DIGITAL designates 
declining. An element is designated declining 
when BASIC has a preferred and often more 


powerful capablity. When you specify 
FLAG:DECLINING, BASIC will flag the following 
source code: 


e CVT$$ (use EDIT$) 


e CVT$%, CVT$F, CVT%$, CVTF$, and SWAP% 
(use multiple MAP statements) 
e DEF* functions (use DEF functions) 


(continued on next page) 
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Table 17: BASIC—-PLUS—2 Command Qualifiers (Cont.) 


ee 
[NO]JIND BUILD 
SEF 


REMAP) 
LIBRARY: lib-param 


e GOTO lin-num% (do not use the integer suffix 
with a line number) 


Causes the Task Builder to include the code 
needed for indexed file operations. BASIC—PLUS—2 
enables this qualifier automatically for programs 
containing an OPEN statement with an 
ORGANIZATION INDEXED clause. 


Lets you specify a memory-resident library to be 
linked to your program. File-spec and lib-nam can 


lib-nam be a library supplied with BASIC—PLUS-—2 or a 
lib-param: file-spec user-created library. If you specify only a lib-nam 
NONE with no device, BASIC assumes LB: on RSTS/E sys- 


tems and LB:[{1,1] on RSX systems. NONE tells the 
Task Builder not to link your task to the default 
memory-resident library. Therefore, the Task 
Builder links to the BASIC disk-resident, object 
module library, BP2OTS.OLB. See the LIBRARY 
command syntax rules for more information on 
memory-resident libraries. 


COMPILE 
RUN 
SET 


[NO]JLIST COMPILE 
SET 


LONG COMPILE 
RUN 
SET 
[NO]MACRO COMPILE 
SET 


92 BASIC Reference Manual 


[NOJLINE Includes line number information in object 
modules. If you specify NOLINE in a program con- 
taining a RESUME statement or using the run-time 
ERL function, BASIC warns that the NOLINE quali- 


fier has been overridden. 


Tells BASIC to produce a source listing file. The 
listing file takes the name of the program and a 
default file type of LST. 


Causes the compiler to allocate 32 bits of storage 
as the default size for all integer data not explicitly 
typed in the program. Untyped integer values are 
treated as LONG values and must be in the LONG 
range or BASIC signals the error ‘Integer error’. 
Table 2 in this manual lists BASIC data types and 
ranges. 


Converts the program into MACRO source code 
and saves it in a file with the same name as the 
program and a file type of MAC. The MAC file can 
be assembled. 


(continued on next page) 


Qualifiers 


enn Am. 
ommana Qua 


=| 
& 
oa 
© 
om 
“I 
w 
> 
— 
c ) 
at 
rf" 
C 
si 
nN 
CY 


[NO]MAP BUILD 


[NOJOBJECT COMPILE 
SET 


Includes information for the allocation map in the 
Task Builder command file. 


Generates an object module with the same file 
name as the program and a default file type of OBJ. 
Ilse NOOBIECT to check your program for errors 


WV yew Me revocm 


without creating an object file. 


Lets you specify an ODL file to describe the RMS 
overlay structure to be used by the Task Builder. 
File-spec can be an ODL file supplied by RMS or a 
user-created file. NONE tells the Task Builder not 
to link your task to the default ODL file. See the 
ODLRMS command syntax rules in this manual for 
more information on ODL files. 


ODLRMS:  odl-param 


file-spec 


od!-param: NONE 


COMPILE 
SET 


[NO]REL BUILD 
SET 


RMSRES: _ lib-param 
COMPILE 
[NO]SEQ BUILD 
SET 
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Sets the page size for the listing file. Int-const must 
be greater than zero or BASIC signals the warning 
“Listing length out of range — ignored”. 


PAGE_SIZE: ini-const 


Causes the Task Builder to include the code 
needed for relative file operations. BASIC—PLUS—2 
sets this qualifier automatically for programs con- 
taining an ORGANIZATION RELATIVE clause in 
an OPEN statement. 


Lets you specify an RMS library that supplies code 
for file and record operations to be linked to your 
program. File-spec can be a library supplied by 
RMS or a user-created library. NONE tells the Task 
Builder not to link your task to the default RMS 
library. See the RMSRES command syntax rules for 


more information on RMS libraries. 


file-spec 


lib-param: NONE 


Allows control of accumulated round-off errors 
when double precision numbers (values typed 
DOUBLE) are used. Numbers are stored as multi- 
ples of 10 by setting the scale factor (const) from 0 
to 6. Floating-point numbers are truncated to an 
integer value of 0 to 6. A scale factor larger than 6 
causes BASIC to signal the error message ‘‘Scale 
factor of n is out of range.”’ 


[NO]SCALE: const 


Causes the Task Builder to include the RMS—11 
code needed for sequential file operations. 
BASIC—PLUS-2 sets this qualifier automatically for 
programs containing an ORGANIZATION 
SEQUENTIAL clause in the OPEN statement. 


(continued on next page) 


Qualifiers 


Table 17: BASIC-PLUS—2 Command Qualifiers (Cont.) 


ee 


SINGLE COMPILE Causes the compiler to allocate 32 bits of storage 
RUN as the default size for all floating-point data not 
SET explicitly typed in the program. Untyped floating- 


point values are treated as SINGLE values and must 
be in the SINGLE range or BASIC signals the error 
“Floating-point error’. Table 2 in this manual lists 
BASIC data types and ranges. 


[NO]SYNTAX_CHECK COMPILE Tells BASIC to perform syntax checking after each 
RUN program line is typed. 
SET 
TYPE_DEFAULT: default-clause COMPILE Sets the default data type (REAL or INTEGER) for all 
RUN data not explicitly typed in your program or speci- 
REAL SET fies that all data must be explicitly typed 
default-clause: INTEGER (EXPLICIT). 
EXPLICIT 


e REAL specifies that all data not explicitly typed is 
floating-point data of the default size (SINGLE or 
DOUBLE). 


e INTEGER specifies that all data not explicitly 
typed is integer data of the default size (BYTE, 
WORD, or LONG). 


e EXPLICIT specifies that all data in a program 
must be explicitly typed. Implicitly declared vari- 
ables cause BASIC to signal an error. 


VARIANT: int-const COMPILE Establishes int-const as a value to be used in com- 
RUN piler directives. The variant value can be refer- 
SET enced i. a lexical expression by using the lexical 
function, %VARIANT. Int-const always has a data 
type of WORD. 


Causes the Task Builder to include the RMS code 
needed for virtual array and block |/O file opera- 
tions. BASIC-PLUS—2 sets this qualifier automati- 
cally when you compile a program containing an 
ORGANIZATION VIRTUAL clause in the OPEN 


statement. 


(continued on next page) 
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Qualifiers 


a 


COMPILE 
SET 


WIDTH: int-const 


Sets the width of the listing file. Int-const must be 
in the range 72 to 132, inclusive, or BASIC signals 
the warning “Listing width out of range — 
ignored’’. 


COMPILE Causes the compiler to allocate 16 bits of storage 
RUN as the default for all integer data not explicitly 
SET typed in the program. Untyped integer values are 
treated as WORD values and must be in the range 
—32768 to 32767 or BASIC signals the error 
“Integer error.” Table 2 in this manual lists BASIC 
data types and ranges. 


* RSX only 
** —RSTS/E only 
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RENAME 


23.0 RENAME 


Function 


The RENAME command allows you to assign a new name to the program currently in memory. 
BASIC does not write the renamed program to a file until you save the program with the REPLACE or 
SAVE command. 


Format 


Syntax Rules 


1. Prog-nam specifies the new program name. VAX—11 BASIC and BASIC—PLUS—2 on 
RSX—11M/M-PLUS systems allow names to contain up to nine alphanumeric characters. 
BASIC—PLUS—2 on RSTS/E systems allows names to contain up to six alphanumeric 
characters. 


2. The program you want to rename must be in memory. If you type RENAME with no 
program in memory, BASIC renames the default program, NONAME, to the specified 
prog-nam. 


VAX—11 BASIC 


1. If you do not specify a prog-nam, VAX—11 BASIC renames the program currently in mem- 
ory NONAME. 


2. If you specify a file type, VAX—11 BASIC signals the error “error in program name’”’. 
BASIC—PLUS—2 


1. BASIC—PLUS-—2 prompts for the new prog-nam if you do not specify one with the 
RENAME command. !f you do not specify a prog-nam in response to the prompt, the name 
of the program currently in memory remains unchanged. 


2. If you specify a file type, BASIC—PLUS-2 ignores the file type, does not signal an error, and 
assigns the B2S file type to the file when you save it. 


General Rules 


1. You must type SAVE or REPLACE to write the renamed program to a file. If you do not type 
SAVE or REPLACE, BASIC does not save the renamed program. 


2. The RENAME command does not affect the original saved version of the program. For 
example: 


OLD TEST 
Ready 


RENAME NEWTES 
Ready 


SAVE 
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RENAME 


In this example, the OLD command calls the program named TEST into memory. The 
RENAME command renames TEST to NEWTES and the SAVE command writes 
NEWTES. BAS (VAX—711 BASIC) or NEWTES.B2S (BASIC—PLUS-—2) to a file. The original file, 
TEST.BAS or TEST.B2S, is not changed and is not deleted from your account. 

Examples 


RENAME NEWPRO 


96 BASIC Reference Manual 


REPLACE 


24.0 REPLACE 


Function 


The REPLACE command writes the current program to a storage medium. 


Format 


REPLACE [ file-spec ] | 


Syntax Rules 


1. 


If you do not supply a file-spec, BASIC writes the program to the default disk with the file 
name of the program currently in memory. 


e VAX—17 BASIC and BASIC-PLUS—2 on RSX-11M/M-PLUS systems create and save a 
new version of the file, incrementing the version number by one. Previous versions of the 
file remain unchanged. 


e BASIC-PLUS—2 on RSTS/E systems overwrites the original version of the file with the 
new version. 


General Rules 


1. 


De 


Examples 


The file-spec does not have to match that of the program currently in memory. You can 
differentiate a changed program from the original version of the program by specifying a 
new file-spec. BASIC saves the program with the new file-spec. 


The program currently in memory does not change. 


REPLACE PROGA.NEW 
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RESEQUENCE 


25.0 RESEQUENCE (VAX-11 BASIC) 


Function 


The RESEQUENCE command allows you to resequence the line numbers of the program currently in 
memory. BASIC also changes all references to the old line numbers so they reference the new line 


numbers. 


Format 


RESEQUENCE [ lin-num1 [ — lin-num2 ][ lin-num3 ] ] [ STEP int-const ] 


Syntax Rules 


1. 


Lin-num1 is the line number in the program currently in memory where resequencing 
begins. The default for lin-num1 is the first line of the program module. 


Lin-num2 is the optional end of the range of line numbers to be resequenced. If you specify 
a range, BASIC begins resequencing with /in-num1 and resequences through /in-num2. If 
you do not specify lin-num2, BASIC resequences the specified line. If you do not specify 
either lin-num1 or lin-num2, BASIC resequences the entire program. 


Lin-num3 specifies the new first line number; the default number for the new first line 
is 100. 


e If lin-num3 will cause existing lines to be deleted or surrounded, BASIC signals an error. 


e You can specify lin-num3, the new first line number, only when resequencing a range of 
lines. 


Int-const specifies the numbering increment for the resequencing operation. The default for 
int-const ts 10. 


BASIC signals an error when you try to resequence a program that contains a %IF directive. 
BASIC also signals an error when you try to resequence a program that has a %INCLUDE 
directive if the file to be included contains a reference to a line number. 


General Rules 


1. 


98 


Before the RESEQUENCE command executes, BASIC verifies the syntax of the program. If 
the program is not syntactically valid, the RESEQUENCE command does not execute. 


BASIC sorts the renumbered program in ascending order when the RESEQUENCE com- 
mand executes. 


If the renumbering creates a line number greater than the maximum line number of 32767, 
BASIC signals an error. 


BASIC signals an error if resequencing causes a change in the order in which program 
statements are to execute and does not resequence the program. 


BASIC issues the error ‘‘undefined line number” in the case of undefined line numbers and 
does not resequence the program. 


BASIC Reference Manual 


cn 


Examples 


RESEQUENCE 


BASIC does not modify the program currently in memory when the RESEQUENCE com- 
mand generates an error. 


In general, the RESEQUENCE command is not recommended for programs containing error 
handlers that test the value of ERL. However, the RESEQUENCE command correctly modi- 
fies the program if the tests that reference ERL are of this form: 


ERL relational-orerator int-lit 


The RESEQUENCE command does not correctly renumber programs if the test compares 
ERL with an expression or a variable, or if ERL follows the relational operator. The follow- 
ing line number references, for example, would not be correctly renumbered: 


IF ERL = 1000 + AX THEN oe. 
IF 1000 > ERL THEN .«.-. 


RESEQUENCE 100-1000 STEP 53 
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RMSRES 


26.0 RMSRES (BASIC-PLUS-2) 
Function 


The RMSRES command allows you to select an RMS memory-resident library to be used when your 
program is task built. You can also choose to use no RMS memory-resident library. The RMS library 
supplies RMS code for file and record operations. After you specify a library with the RMSRES 
command, when you use the BUILD command, BASIC—PLUS-—2 includes the specified library in the 
Task Builder command file. Every system has an RMS library default set when BASIC—PLUS—2 is 
installed. 


Format 


RMSRES lib-param 


lib-param: file-spec 
NONE 


Syntax Rules 


1. If you enter the RMSRES command without a lib-param, BASIC—PLUS—2 prompts for one 
and displays the name of the current default RMS library. 


e File-spec can be RMSRES (the RMS memory-resident library) or a user-created resident 
library. Table 18 lists and describes RMS libraries. 


e¢ NONE tells the Task Builder not to link your task to the RMS default resident library. 
Therefore, the Task Builder links to the RMS object module library, RMSLIB.OLB. 


¢ If you type a carriage return in response to the prompt, the current default memory- 
resident library is used. 


General Rules 


1. LB: is a RSTS/E logical name for the library account on disk. On RSX—11M/M-PLUS 
systems, you must specify LB:[1,1] before the ODL file name. 


2. BASIC~PLUS—2 links the specified RMS library to your program when you task-build the 
program. You must use the RMSRES command before you use the BUILD command to 
include the specified library in the Task Builder command file. 


3. If you use an RMS library other than the default, you must specify one of the RMS ODL 
files listed in Table 18. See the ODLRMS compiler command for more information. 
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RMSRES 


he RMSRES library you specify is included in your Task Builder command files until you 
a new library with the RMSRES command or exit from the BASIC environment. 
When you exit from the environment, the original RMS default library is restored as the 


default. 


fa 


5. You can override the RMSRES command with the /RMSRES qualifier added to the BUILD 
command, but the specified library remains in effect for only one BUILD routine. 


6. The Task Builder returns an error message when the requested library is not available. 


7. Consult your system manager for information about the RMS libraries available to you. 
Consult BASIC on RSX-11M/M-—PLUS Systems or BASIC on RSTS/E Systems for more 
information on using RMS libraries 


Table 18: RMS Libraries 


Library File Organization Type of ODL File 
Name Library Required 


RMSRES RMSRLX.ODL 
DAPRES DAPRLX.ODL 
RMS11S.ODL 
RMS12S.ODL 
RMSLIB RMS11X.ODL 
RMS12X.ODL 
DAP11X.ODL 


Examples 


RSX-11M/M—PLUS Systems 
RMSRES LB:C1+1IRMSRES 


RSTS/E Systems 
RMSRES LB:RMSRES 
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RUN 


27.0 RUN and RUNNH 


Function 


The RUN command allows you to execute a program from the BASIC environment without first 
invoking the PDP—11 Task Builder or the VAX—717 Linker to construct an executable image. The 
program can be: 


e A BASIC program brought into memory with the OLD command, created in response to the NEW 
command, or specified in the RUN command 


e An object module or modules placed in memory with the LOAD command 
e A combination of the above 


RUN executes the program starting at the lowest line number. Program modules previously compiled 
and placed in memory with the LOAD command are referenced when the RUN command is given. 
RUNNH executes the program but does not display the program header. 

Format | 


VAX-11 BASIC 


[ file-spec ] 


BASIC—PLUS—2 


RUNNH 
| RUN | [ file-spec ] [ /qualifier ]... 


Syntax Rules 


1. If you specify only the file name, BASIC searches for a file with a BAS (VAX—11 BASIC) or 
B2S (BASIC—PLUS-—2) file type in the current default directory. 


2. If you do not supply a file-spec, BASIC executes the program currently in memory. 


3. BASIC signals the warning message ‘‘No main program” if you do not supply a file-spec 
and do not have a program currently in memory. 


4. The RUNNH command is identical to RUN, except that it does not display the program 
header, current date, and time. 


BASIC—PLUS—2 


1. /Qualifier specifies a qualifier keyword that sets a BASIC default. See Section 22.0 for 
information on BASIC qualifiers. Table 17 lists all BAS/C—PLUS—2 qualifiers and the com- 
mands they can be used with, and describes their functions. 


2. Support for RUN is an installation option. Use the SHOW command to see whether your 
system supports the RUN command. 
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RUN 


General Rules 


1. When you specify a file-spec with the RUN command, BASIC brings the program into 
memory and then executes it. You do not have to bring a program into memory with the 
OLD command in order to run it. The RUN command executes just as if the program had 
been brought into memory with the OLD command. 


2. lf your program calls a subprogram, the subprogram must be compiled and placed in 
memory with the LOAD command. If your program tries to call a subprogram that has not 
been compiled and loaded, BASIC signals an error. 


3. The RUN command does not create an object module file or a listing file. 


VAX-11 BASIC 


1. The program stops executing and control passes to the BASIC environment and immediate 
mode when BASIC encounters a STOP statement in the program. 


e Any BASIC statement that does not require the creation of new storage can be entered in 
immediate mode to debug the program. You cannot create new variables in immediate 
mode. 


e Type the CONTINUE command to resume program execution. 


2. The RUN command uses whatever qualifiers have been set with the exception of those that 
have no effect on a program running in the environment. These are: 


¢ NOCROSS 

¢ NODEBUG 

e NOLIST 

¢ NOMACHINE 

¢ NOOBJECT 

These qualifiers are always in effect when you run a program in the environment. 
BASIC—PLUS—2 


1. The program stops executing when BASIC encounters a STOP statement: 


e If you used the RUN command to execute the program, BASIC displays a pound sign (#) 
prompt. In response to the prompt, you can type only CONTINUE to resume program 
execution, or EXIT to end the program. 


e If you used the RUN/DEBUG command to execute the program, control passes to the 
BASIC—PLUS—2 debugger. You can then use BASIC—PLUS—2 debugger commands to 
display and change program values and to analyze your program. Use the CONTINUE 
debugger command to resume program execution. See Part VI in this manual for more 
information on debugger commands. 


Examples 


RUN PROGI 


BASIC Reference Manual 103 


SAVE 


28.0 SAVE 


Function 


The SAVE command writes the BASIC source program currently in memory to a file on the default or 
specified device. 


Format 


SAVE [ file-spec ] 


Syntax Rules 


1. If you do not supply a file-spec, BASIC saves the file with the name of the program 
currently in memory and the BAS (VAX—11 BASIC) or B2S (BASIC~PLUS-—2) default file 
type. 


2. If you specify only the file name, BASIC saves the program with the default file type in the 
current default directory. 


General Rules 


1. In BASIC—PLUS—2, if you type SAVE and the file-spec already exists as a disk file, BASIC 
displays the message ‘‘File exists — Rename or Replace”. 


2. VAX-11 BASIC writes a new version of a previously saved program when you type the 
SAVE command. 


3. BASIC stores the sorted program in ascending line number order. 


4. You can store the program on a specified device. For example: 
SAVE DBAL:NEWTST.PRO 


BASIC saves the file NEWTST.PRO on disk DBA1:. 
Examples 


SAVE JUNK.BAS 
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SCALE 


29.0 SCALE 
Function 
The SCALE command allows you to control accumulated round-off errors by multiplying numeric 


values by 10 raised to the scale factor before storing them. 


Format 


| SCALE int-const 


Syntax Rules 


1. In BASIC—PLUS—2, SCALE with no argument causes BASIC to display the message ‘’Current 
scale factor is n’’, where n is an integer from O to 6 inclusive. In VAX—17 BASIC, SCALE 
with no argument causes BASIC to signal the error “illegal argument for command”’. 


2. Int-const specifies the power of 10 you want to use as the scaling factor. 


e In VAX—17 BASIC, int-const must be an integer from 0 to 6, inclusive, or BASIC signals 
the error ‘‘illegal argument for command”. 


® In BASIC—PLUS—2, int-const can be a floating-point or integer number up to 6.999999. 
BASIC truncates a floating point value and displays the message ‘‘%Scale factor has been 
truncated to n’’, where n is the integer portion of the value. If the specified value is 
greater than 6.999999, BASIC signals the error ‘‘Scale factor of n is out of range’’, where 
n is the specified value. 


General Rules 
fects only values of the data type DOUBLE. 


2. BASiC multiplies values using the scale factor you specify. The value 2.488888, for 
example, is rounded as follows: 


Examples 


SCALE 2 
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SCRATCH 


30.0 SCRATCH 


Function 


The SCRATCH command clears any program currently in memory, removes any object files loaded 
with the LOAD command, and resets the program name to NONAME. 


Format 


SCRATCH 


Syntax Rules 


None. 


General Rules 


None. 
Examples 


SCRATCH 
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Function 


SEQUENCE 


The SEQUENCE command causes BASIC to automatically generate line numbers for your program 
text. BASIC supplies line numbers for your text until you end the procedure or reach the maximum 
line number of 32767. 


Format 


by eae wet asnktustenasa © Oe 
| SEQUENCE [ lin-num ][ , int-const ] | 


Syntax Rules 


1 


Lin-num specifies the line number where sequencing begins. 


e If you do not specify a lin-num, the VAX—11 BASIC default is the last line inserted by a 
SEQUENCE command; if there is no previous SEQUENCE command, the default is line 
number 100. 


e The BASIC—PLUS-—2 default lin-num is always line number 100. 


Int-const specifies the line number increment for your program. 


e If you do not specify an increment, VAX—11 BASIC defaults to the int-const specified in 
the last SEQUENCE command; if there is no previous SEQUENCE command, the default 
is 10. 


e BASIC—PLUS—2 always defaults to 10. 


General Rules 


1. 


6. 


Examples 


If you specify a lin-num that already contains a statement, or if the sequencing operation 
generates a line number that already contains a statement, BASIC signals ‘Attempt to 
sequence over existing statement’, and returns to normal input mode. 


Enter your program text in response to the line number prompt; the carriage return ends 
each line and causes BASIC to generate a new line number. 


If you enter a CTRL/Z in response to the line number prompt, BASIC terminates the 
sequencing operation and prompts for another command. 


You can also terminate the sequence operation in BASIC—PLUS—2 by typing a carriage 
return in response to the line number prompt. 


When the maximum line number of 32767 is reached, BASIC terminates the sequencing 
process and returns to normal input mode. 


BASIC does not check syntax during the sequencing process. 


SEQUENCE 100;10 
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SET 


32.0 SET 


Function 


The SET command allows you to specify BASIC defaults for all BASIC qualifiers. Qualifiers control the 
compilation process and the run-time environment. Qualifiers are set or reset as you specify. The 
defaults you set remain in effect for all subsequent operations until they are reset or until you exit from 
the compiler. 


Format 


SET 


qualifier... 
/qualifier... 


Syntax Rules 


Ic 


/Qualifier specifies a qualifier keyword that sets a BASIC default. See Section 22.0 for 
information on BASIC qualifiers. Table 16 lists and describes all VAX—71 BASIC qualifiers. 
Table 17 lists and describes all BASIC—PLUS—2 qualifiers. 


If you do not specify any qualifiers, VAX—11 BASIC resets all defaults to the defaults 
specified with the DCL BASIC command. 


If you do not specify any qualifiers, BAS/C—PLUS—2 resets all qualifiers except those set 
with the BRLRES, DSKLIB, LIBRARY, ODLRMS, RMSRES, or EXTEND qualifier to the 
installation defaults. The SCALE value set with the SCALE command is also not reset to the 
installation default. 


VAX—11 BASIC signals the error ‘‘unknown qualifier’’ and BASIC—PLUS—2 signals ‘Illegal 
switch’”’ if you do not separate multiple qualifiers with commas or slashes, or if you mix 
commas and slashes on the same command line. The same error is signaled if you separate 
qualifiers with a slash but do not prefix the first qualifier with a slash. 


General Rules 


None. 


Examples 


SET /DOUBLE/BYTE/LIST 
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SHOW 


Function 
The SHOW command displays the current defaults for the BASIC compiler on your terminal. 


Format 


SHOW 


Syntax Rules 


None. 


General Rules 


None. 


Examples 
VAX—11 BASIC 


SHOW 
VAX-11 BASIC V2. Current Environment Status 11-DEC-1982 10:065:56.57 
DEFAULT DATA TYPE INFORMATION: LISTING FILE INFORMATION INCLUDES: 
Data type : REAL NO Source 
Real size : SINGLE NOQ Cross reference 
Integer size +: LONG COD Definitions 
Decimal size : (15:2) Environment 
Scale factor : 6 NO Override of ZNOLIST 
NO Round decimal numbers NO Machine code 
Map 
COMPILATION QUALIFIERS IN EFFECT: INCLUDE files 
ObJject file 
Overflow check integers FLAGGERS: 
Overflow check decimal numbers Declining features 
Bounds checking NO BASIC PLUS 2 subset 
NO Syntax checking 
Lines 
Variant +: 0 DEBUG INFORMATION: 
Warnings Traceback records 
Informationals NO Debug symbol records 
Setup 


Object Libraries : NONE 
Ready 


BASIC—PLUS—2 


SHOW 

PDOP-11 BASIC-PLUS-2 V2.0 

ENVIRONMENT INFORMATION: RMS FILE ORGANIZATION: 
Current edit line : 0 NO Index 
NO Modules loaded NO Relative 
NO Main module loaded NO Sequential 


Run surPrort NO Virtual . 
(continued on next page) 
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SHOW 


DEFAULT DATA TYPE INFORMATION: 


Data tyre : REAL 

Reai size : SINGLE 

Integer size : WORD 

Scale factor : 0 
COMPILATION QUALIFIERS: 

NO ObJect 

NO Macro 

Lines 

NO Debug records 

NO Syntax checking 

Flag : Declining 

Variant : 0 
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LISTING FILE INFORMATION: 

NO Source 

NO Cross Reference 

NO Keywords 

60 lines by 132 columns 

BUILD QUALIFIERS: 

NO Dump 

NO Map 

Task extend : 312 

RMS ODL file : LB:RMSRLX 

BP2 Disk lib : LB:BP20TS 

BP2 Resident lib : LB: BP2RES 

RMS Resident lib : LB:RMSRES 


UNSAVE 


34.0 UNSAVE 


Function 


The UNSAVE command deletes a specified file from storage. 


Format 


UNSAVE [ file-spec ] 


Syntax Rules 
1. File-spec is optional. 


e If you do not supply a file-spec, BASIC deletes a file that has the file name of the program 
currently in memory and a file type of BAS (VAX—11 BASIC) or B2S (BASIC—PLUS—2). 


e If you do not supply a file-spec and do not have a program in memory, BASIC searches 
for the default file NONAME.BAS. 


2. You do not have to supply a full file-spec. If you specify only a file name, BASIC deletes the 
file with the specified name and the BAS (VAX—11 BASIC) or B2S (BASIC—PLUS-2) file type 
from the default device and directory. Other file types with the same file name are not 
deleted. 


General Rules 


1. The program currently in memory does not change even when it is the deleted file because 
it is a copy of the deleted file. 


Examples 


UNSAVE DB2:CHECK.DAT 
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PART III 
Compiler 
Directives 


%ABORT 


1.0 %ABORT 


Function 


The %ABORT directive terminates program compilation and displays a fatal error message you 
supply. 


Format 


(ene ee ee ee ee ee ee eee Ce 


| %ABORT [ str-lit ] | 


Syntax Rules 
1. The %ABORT directive cannot begin in column one. 


2. Only a line number or a comment field can appear on the same physical line as the 
% ABORT directive. 


General Rules 


1. BASIC stops the compilation and terminates the listing file as soon as it encounters a 
%ABORT directive. Str-lit is displayed on the terminal screen and in the compilation 
listing, if one has been requested. 


Examples 
100 ZIF ZVARIANT = 2 ZTHEN 
ZABORT "Cannot compile with variant 2" 
%ZEND ZIF 
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%CROSS 


2.0 %CROSS 


Function 


The %CROSS directive causes BASIC to begin or resume accumulating cross-reference information 
for the listing file. 


Format 


%CROSS 


Syntax Rules 
1. The %CROSS directive cannot begin in column one. 


2. Only a line number or a comment field can appear on the same physical line as the 
%CROSS directive. 


General Rules 


1. When a cross-reference is requested, the compiler starts or resumes accumulating cross- 
reference information immediately after encountering the %CROSS directive. 


Examples 


1000 4CROSS 


114 BASIC Reference Manual February 1984 


%|IDENT 


3.0 %IDENT 


Function 


The %IDENT directive lets you identify the version of a program module. The identification text is 
placed in the object module and printed in the listing header. 


Format 


| %IDENT sir-iit | 


Syntax Rules 


1.  Str-lit is the identification text. VAX—71 BASIC allows str-lit to consist of up to 31 ASCII 
characters. BASIC—PLUS—2 allows str-lit to consist of up to six RAD—50 characters. Both 
truncate extra characters from str-lit and signal a warning message. 


2. In BASIC—PLUS—2, if str-lit contains non—RAD—50 characters, a warning message is 
issued, and the %IDENT directive is ignored. See BASIC on RSX—11M/M-—PLUS Systems 
or BASIC on RSTS/E Systems for more information on RAD—50 characters. 


3. The %IDENT directive cannot begin in column one. 


4. Only a line number or a comment field can appear on the same physical line as the 
%IDENT directive. 


General Rules 


1. The compiler inserts the identification text in the first 6 or 31 character positions of the 
second line on each listing page. The compiler also includes the identification text in the 
object module, if the compilation produces one, and in the map file created by the Task 
Builder (BASIC—PLUS—2) or the VAX—11 Linker. 


2. The %IDENT directive should appear at the beginning of your program if you want the 
identification text to appear on the first page of your listing. If the %IDENT directive 
appears after the first program statement, the text will appear on the next page of the listing 
file. 


3. You can use the %IDENT directive only once in a module. If you specify more than one 
%IDENT directive in a module, BASIC signals a warning and uses the identification text 
specified in the first %IDENT. 
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%IDENT 


The default BASIC—PLUS—2 identification text is a 6~digit number. The first two digits 


represent the compiler base level, while the last four digits represent the month and day. 


For example, the identification text 100712 represents base level 10, and a date of July 12. 


5. VAX-11 BASIC does not provide a default identification text. 


Examples 


100 


116 


41IDENT "V3.2" 
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%|IF—-~THEN—%ELSE—%END—%IF 
4.0 %iF—% THEN—%ELSE—-%END—%IF 
Function 


The %IF—%THEN—%ELSE—~%END—%IF directive lets you conditionally include source code or exe- 
cute another compiler directive. 


Format 


| %IF lex-exn %THEN code [ %ELSE code ] %END %IF | 


/ 


Syntax Rules 


1. The %IF directive can appear anywhere in a program where a space is allowed, except in 
column one or within a quoted string. This means that you can use the %IF directive to 
make a whole statement, part of a statement, or a block of statements conditional. 


2.  Lex-exp is always a LONG integer in VAX—11 BASIC and a WORD. integer in 
BASIC—PLUS—2. It can be: 


¢ A lexical constant named in a %LET directive. 
e An integer literal, with or without the percent sign suffix. 


e A lexical built-in function (% VARIANT). 


e Any combination of the above, separated by valid lexical operators. Lexical operators 
(+), subtraction (—), multiplication (*), and division (/). 


3. Code is BASIC program code. It can be any BASIC statement or another compiler directive, 
including another %IF directive. You can nest %IF directives to eight levels. 


4. %THEN, %ELSE, and %END %IF do not have to be on the same physical line as %IF. 


General Rules 


1. If lex-exp is true, BASIC processes the %THEN clause. If lex-exp is false, BASIC processes 
the %ELSE clause. If there is not an %ELSE clause, BASIC processes the %END %IF clause. 
The compiler includes statements in the %THEN or %ELSE clause in the source program 
and executes directives in order of occurrence. 


2. You must include the %END %IF clause. Otherwise, BASIC assumes the remainder of the 


program is part of the last %THEN or %ELSE clause and signals the error ‘‘missing %END 
%IF’’ when compilation ends. 
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%IF—-% THEN—%ELSE—%END—%IF 


Examples 


109 KIF (ZVYARIANT = 2) 
ZTHEN DECLARE SINGLE HOURLY_PAY(100) 
ZELSE ZIF (ZVARIANT = 1) 
%ZTHEN DECLARE DOUBLE SALARY_PAY(100) 
ZELSE ZABORT “Can’t compile with specified variant" 


ZEND ZIFF 
ZEND AIF 
1000 PRINT ZIF (ZVARIANT = 2) 


%ZTHEN PRINT ‘Hourly Wage Chart’ 
GOTO Hourly_ routine 

%ELSE PRINT ‘Salaried Wage Chart’ 
GOTO Salary_routine 

ZEND ZIF 
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%INCLUDE 


5.0 %INCLUDE 
Function 


The %INCLUDE directive lets you include BASIC source text from another program file in the current 
program compilation. VAX—171 BASIC also lets you access record definitions in the VAX—11 Common 
Data Dictionary (CDD). 


Format 


Ranara I 
UCciicia 


%INCLUDE file-spec 


VAX-11 BASIC 


%INCLUDE %FROM %CDD str-lit 


Syniax Rules 
1. The %INCLUDE directive cannot begin in column one. 


2. Only a line number or a comment field can appear on the same physical line as the 
%INCLUDE directive. 


3.  File-spec specifies the file to be included. BASIC uses the default device, directory, and file 
type (BAS in VAX—11 BASIC and B2S in BASIC—PLUS-—2) if you do not specify these parts of 
the file specification. 


4. File-spec must be a disk file or BASIC signals an error. 
5.  File-spec must be a string literal enclosed in quotation marks. 


VAX—11 BASIC only 


1. Str-lit specifies a VAX—11 CDD path specification. This lets you extract a RECORD defini- 
tion from the CDD. 


2. There are two types of CDD path names: absolute and relative. An absolute path name 
begins with CDD$TOP and specifies the complete path to the record definition. A relative 
path name begins with any string other than CDD$TOP. 


General Rules 


1. The compiler includes the specified source file in the program compilation at the point of 
the %INCLUDE directive and prints the included code in the program listing file if the 
compilation produces one. 


2. The included file cannot contain line numbers or BASIC signals the error “Line number 
may not appear in %INCLUDE file’’. 
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%INCLUDE 


4. 
5. 


All statements in the accessed file are associated with the line number of the program line 
that contains the %INCLUDE directive. This means that a %INCLUDE directive cannot 
appear before the first line number in a source program. 


A file accessed by %INCLUDE can itself contain a %INCLUDE directive. 


All %IF directives in an included file must have a matching %END %IF directive in the file. 


VAX-11 BASIC only 


i 


Examples 


General 


100 


You can control whether or not included text appears in the compilation listing with the 
/SHOW:INCLUDE qualifier. When you specify /SHOW:INCLUDE, the compilation list- 
ing file identifies any text obtained from an included file by placing a mnemonic in the first 
character position of the line on which the text appears. The mnemonic is of the form “In” 
where ‘‘I’’ tells you that the text was accessed with a %INCLUDE directive and ‘‘n” is a 
number that tells you the nesting level of the included text. See the BASIC User’s Guide for 
more information on listing mnemonics. 


When you use the %INCLUDE directive to extract a record definition from the CDD, 
BASIC translates the CDD definition to the syntax of the BASIC RECORD statement. 


You can use the /SHOW:CDD_DEFINITIONS to specify that translated CDD definitions 
(in RECORD statement syntax) are included in the compilation listing file. BASIC places a 
“C’’ in column one when the translated RECORD statement appears in the listing file. 


When you do not specify /SHOW:CDD_DEFINITIONS, BASIC includes the names, data 
types, and offsets of the CDD record components in the program listing’s allocation map. 


See BASIC on VAX/VMS Systems and the VAX—11 Common Data Dictionary Utilities 
Reference Manual for more information on CDD definitions. 


ZINCLUDE "YESNO" 


VAX—11 BASIC only 


1000 


ZINCLUDE ZFROM £CDD "CDDSTOP.EMPLOYEE"” 
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%LET 


Function 


The %LET directive declares and provides values for lexical constants. You can use lexical constants 
only in conditional expressions in the %IF—%THEN—%ELSE directive and in lexical expressions in 
subsequent %LET directives. 


Format 


a me ey ame ee ee ee eee ae ee 
| %LET %lex-const-nam = lex-exp | 


Syntax Rules 


1. Lex-const-nam is the name of a lexical constant. Lexical constants are always LONG 
integers in VAX—11 BASIC and WORD integers in BASIC—PLUS-2. 


2. Lex-const-nam must be preceded by a percent sign and cannot end with a dollar sign ($) or 
percent sign. 


3.  Lex-exp can be: 
e A lexical constant named in a previous %LET directive. 
e An integer literal, with or without the percent sign suffix. 
e A lexical built-in function (%VARIANT) 


e Any combination of the above, separated by valid lexical operators. Lexical operators 
may be logical operators, relational operators, and the arithmetic operators for addition 
(+), subtraction (—), multiplication (*), and division (/). 


4. The %LET directive cannot begin in column one. 


5. Only a line number or a comment field can appear on the same physical line as the %LET 
directive. 


General Rules 


1. You cannot change the value of /ex-const-nam within a program unit once it has been 
named in a %LET directive. 


Examples 


100 ZLET ZDEBUG_ON = 1% 
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%LIST 


7.0 %LIST 


Function 


The %LIST directive causes the compiler to start or resume accumulating compilation information for 
the program listing file. 


Format 


%LIST 


Syntax Rules 
1. The %LIST directive cannot begin in column one. 


2. Only a line number or a comment field can appear on the same physical line as the 
%LIST directive. 


General Rules 


1. As soon as it encounters the %LIST directive, the compiler starts or resumes accumulating 
information for the program listing file. Thus, the directive itself appears as the next line in 
the listing file. 


2. The %LIST directive has no effect unless you requested a listing file. 


Examples 


100 ALIST 
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%NOCROSS 


8.0 %NOCROSS 
Function 


The %NOCROSS directive causes the compiler to stop accumulating cross-reference information for 
the program listing file. 


Format 


Syntax Rules 
1. The %NOCROSS directive cannot begin in column one. 


2. Only a line number or a comment field can appear on the same physical line as the 
%NOCROSS directive. 


General Rules 


1. The compiler stops accumulating cross-reference information for the program listing file 
immediately after encountering the %NOCROSS directive. 


2. The %NOCROSS directive has no effect unless you requested cross-reference 
information. 


3. Digital recommends that you not embed a %NOCROSS directive within a statement. 
Embedding a %NOCROSS directive within a statement makes the accumulation of cross- 
reference information behave unpredictably. 


Examples 


1000 4NOCROSS 
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%NOLIST 


9.0 %NOLIST 


Function 


The %NOLIST directive causes the compiler to stop accumulating compilation information for the 
program listing file. 


Format 


%NOLIST 


Syntax Rules 
1. The %NOLIST directive cannot begin in column one. 


2. Only a line number or a comment field can appear on the same physical line as the 
%NOLIST directive. 


General Rules 


1. Assoon as it encounters the %NOLIST directive, the compiler stops accumulating informa- 
tion for the program listing file. Thus, the directive itself does not appear in the listing file. 


2. The %NOLIST directive has no effect unless you requested a listing file. 


3. In VAX-11 BASIC, you can override all %NOLIST directives in a program with the 
/SHOW:OVERRIDE qualifier. 


Examples 


100 4ZNOLIST 
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%PAGE 


10.0 %PAGE 


Function 


The %PAGE directive causes BASIC to begin a new page in the program listing file immediately after 
the line that contains the %PAGE directive. 


Format 
| %PAGE | 
ee ee ee | 


Syntax Rules 
1. The %PAGE directive cannot begin in column one. 


2. Only a line number or a comment field can appear on the same physical line as the 
%PAGE directive. 


General Rules 


None. 


Examples 


1000 4ZPAGE 


BASIC Reference Manual 125 


%SBTTL 


11.0 %SBTTL 


Function 


The %SBTTL directive lets you specify a subtitle for the program listing file. 


Format 


%SBTTL str-lit 


Syntax Rules 


iP 


VAX-11 BASIC allows str-lit to contain 45 characters. BASIC-PLUS—2 allows str-lit to 
contain 48 characters. 


BASIC truncates extra characters from str-lit and does not signal a warning or error. 
The %SBTTL directive cannot begin in column one. 


Only a line number or a comment field can appear on the same physical line as the 
%SBTTL directive. 


General Rules 


1. 


The specified subtitle appears underneath the title on the second line of all pages of the 
listing file until the compiler encounters another %SBTTL or %TITLE directive. 


Because BASIC assumes that a subtitle is associated with a title, a new %TITLE directive 
eliminates the current subtitle. In this case, no subtitle appears in the listing until the 
compiler encounters another %SBTTL directive. 


If you want a subtitle to appear on the first page of your listing, the %SBTTL directive 
should appear at the beginning of your program, immediately after the %TITLE directive. 
Otherwise, the subtitle will appear on the second page of the listing, but not on the first. 


If you want the subtitle to appear on the page of the listing that contains the %SBTTL 
directive, the %SBTTL directive should immediately follow a %PAGE directive or a %TITLE 
directive that follows a %PAGE directive. 


Examples 


100 


126 


Z5BTTL ‘DESMAZ19 Production Elements’ 
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%TITLE 


12.0 %TITLE 


Function 


The %TITLE directive lets you specify a title for the program listing file. 


Format 


%TITLE str-lit 


Syntax Rules 


1. VAX-11 BASIC allows str-lit to contain 45 characters. BASIC—PLUS—2 allows str-lit to 
contain 48 characters. 


2. BASIC truncates extra characters from str-lit and does not signal a warning or error. 
3. The %TITLE directive cannot begin in column one. 


4. Only a line number or a comment field can appear on the same physical line as the 
%TITLE directive. 


General Rules 


1. The specified title appears on the first line of every page of the listing file until BASIC 
encounters another %TITLE directive in the program. 


2. The %TITLE directive should appear on the first line of your program, before the first 
statement, if you want the specified title to appear on the first page of your listing. 


Caer werw we ee POR WU = bed 5 ¥ ; = 5 


%TITLE directive should immediately follow a %PAGE directive. 


3. If you want the specified title to appear on the page that contains the %TITLE directive, the 


4. Because BASIC assumes that a subtitle is associated with a title, a new %TITLE directive 
eliminates the current subtitle. 


Examples 


100 ZATITLE ‘Production Control for DESMAZ19’ 
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%VARIANT 


13.0 %VARIANT 


Function 


%VARIANT is a built-in lexical function that allows you to conditionally control program compila- 
tion. %VARIANT returns an integer value when you reference it in a lexical expression. You set the 
variant value with the /VARIANT qualifier when you compile the program or with the SET command. 


Format 


%VARIANT 


Syntax Rules 


1. The %VARIANT function can appear only in a lexical expression. 


General Rules 


1. The %VARIANT function returns the integer value specified at compile-time with the 
/VARIANT qualifier to the COMPILE command or with the SET command, or in VAX-11 
BASIC, set with the DCL BASIC command. The returned integer always has a data type of 
LONG in VAX—11 BASIC and WORD in BASIC—PLUS-2. 


Examples 


1900 ZIF (ZLOOP_CONST <= ZVARIANT) 
ZTHEN GOTO Tax_Routine 
RELSE ZABORT ‘Variant too iargye for Frogram to compile’ 
ZEND 4IF 
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PART IV 
Statements 


CALL 


1.0 CALL 


Function 


The CALL statement transfers control to a BASIC subprogram or other callable routine. You can pass 
optional arguments to the routine and can specify how these arguments are to be passed. When the 
called routine finishes executing, control returns to the calling program. 


Format 


CALL routine [ pass-mech ] [ ( [ actual-param ],... ) ] 


routine: sub-nam 


any callable routine 


pass-mech: BY REF 
BY VALUE 
BY DESC 


actual-param: exp 
array ( [J]... ) [ pass-mech ] 


Syntax Rules 


1. Routine is the name of the BASIC SUB subprogram you want to call or the name of any 
other callable module, such as a system service or an RTL routine on VAX/VMS systems. It 
cannot be a variable name. 
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2. Pass-mech specifies how arguments are passed to the called routine. If you do not specify a 
pass-mech, BASIC passes arguments as indicated in Tables 19 and 20. 


3. You can use passing mechanisms only when calling non—BASIC routines. 


4. When pass-mech appears before the parameter list, it applies to all arguments passed to the 
called routine. You can override this passing mechanism by specifying a pass-mech for 
individual arguments in the actual-param list. 

5. Actual-param lists the arguments to be passed to the called routine. 


6. You can pass expressions or entire arrays. Optional commas in parentheses after the array 
name specify the dimensions of the array. The number of commas is equal to the number 
of dimensions minus one. Thus, no comma specifies a one-dimensional array, one comma 
specifies a two-dimensional array, two commas specify a three-dimensional array, and 


so on. 
VAX-11 BASIC 
1. The name of the routine can consist of from 1 to 31 characters and must conform to the 
following rules: 


@ The first character of an unquoted name must be an alphabetic character (A through Z). 
The remaining characters, if present, can be any combination of letters, digits (0 through 
9), dollar signs ($), periods (.), or underscores (_). 


e A quoted name can consist of any combination of printable ASCII characters. 


2. Routine can be a system service, an RTL routine, or any procedure written in a language 
that supports the VAX—11 Procedure Calling Standard. See BASIC on VAX/VMS Systems for 
more information on using system services, RTL routines, and other procedures. 


3. VAX-11 BASIC allows you to pass up to 255 parameters. 


4. You cannot pass virtual arrays. 
BP2 BASIC—PLUS—2 


1. The name of the routine can consist of from one to six characters and must conform to the 
following rules: 


@ The first character of an unquoted name must be an alphabetic character (A through Z). 
The remaining characters, if present, can be any combination of letters, digits (0 through 
9), dollar signs ($), or periods (.). 


e A quoted name can consist of any combination of alphabetic characters, digits, dollar 
signs ($), periods (.), or spaces. 


2. Routine can be a BASIC—PLUS—2 subprogram or a subprogram written in another 
language. 


Note 


Although you can call routines written in other languages, BASIC-PLUS—2 does 
not support calling anything but BAS/C—PLUS—2 routines. 
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You can pass all arguments BY REF, but you can pass only string values and entire arrays 
BY DESC. 


BASIC-—PLUS—2 lets you pass up to eight parameters to a BASIC~PLUS—2 subprogram and 
up to 255 parameters to a MACRO-—11 subprogram. 


General Rules 


1. 


ee 


The optional pass-mech clauses tell BASIC how to pass arguments to the called sub- 
program. Table 19 describes VAX—11 BASIC parameter passing mechanisms. Table 20 
describes BASIC—PLUS—2 parameter passing mechanisms. 


e BY REF specifies that BASIC passes the argument’s address. This is the default for all 
arguments except strings and entire arrays. 


® BY VALUE specifies that VAX—17 BASIC passes the argument’s 32-bit value and that 
BASIC—PLUS—2 passes the argument’s 16-bit value. 


® BY DESC specifies that BASIC passes the address of a VAX—17 BASIC descriptor or a 
BASIC—PLUS-—2 descriptor. For information about the format of a VAX—11 BASIC descrip- 
tor for strings and arrays, see Appendix C in BASIC on VAX/VMS Systems; for informa- 
tion on other types of descriptors, see the VAX Architecture Handbook. BASIC~PLUS—2 
creates descriptors only for strings and arrays; these descriptors are described in Appen- 
dix C in BASIC on RSX—-11M/M-—PLUS Systems and BASIC on RSTS/E Systems. 


You can specify a null argument as an actual-param for non—BASIC routines by omitting 
the argument and the pass-mech, but not the commas or parentheses. This forces BASIC to 
pass a null argument as defined by your operating system and allows you to access system 
routines from BASIC. 


Arguments in the actual-param list must agree in data type and number with the formal 
parameters specified in the subprogram. 


An argument is modifiable when changes to it are evident in the calling program. Changing 
a modifiable parameter in a subprogram means the parameter is changed for the calling 
program as well. Variables and entire arrays passed BY DESC or BY REF are modifiable. 


An argument is nonmodifiable when changes to it are not evident in the calling program. 
Changing a nonmodifiable argument in a subprogram does not affect the value of that 
argument in the calling program. Arguments passed BY VALUE, constants, and expressions 
are nonmodifiable. Passing an argument as an expression (by placing it in parentheses) 
changes it from a modifiable to a nonmodifiable argument. 


For expressions and virtual array elements passed BY REF, BASIC makes a local copy of the 
value, and passes the address of this local copy. For dynamic string arrays, BASIC passes a 
descriptor of the array of string descriptors. BASIC passes the address of the argument’s 
actual value for all other arguments passed BY REF. 


No files are closed when the CALL statement executes. 


VAX-—11 BASIC 


1. 


Only BYTE, WORD, LONG, and SINGLE values can be passed by BY VALUE. BYTE and 
WORD values passed by VALUE are converted to LONG values. 
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BASIC—PLUS—2 


1. Only BYTE and WORD values can be passed BY VALUE. BYTE values passed BY VALUE 


eS 


are converted to WORD values. 


2. BASIC—PLUS—2 does not allow recursion. That is, once a subprogram is called, it cannot 
be called again until the SUBEND or SUBEXIT statement has executed or until an error has 
been trapped with ON ERROR GO BACK. 

Examples 


200 CALL SUBi BY REF (EMPNAMES, (2%) BY VALUE,+ D#() BY DESC) 


Table 19: VAX—11 BASIC Parameter Passing Mechanisms 


Argument Type BY VALUE BY REF BY DESC 
Numeric Arguments 


Variables *YES 


Constants *Local copy | Local copy 


Expressions *Local copy 


*YES 


Local copy 


YES 


Array elements 


Virtual array elements Local copy 
*YES 


NO 


*Local copy 
YES 
NO 


Entire arrays 


Entire virtual arrays 


String Arguments 


Variables YES *YES 


Constants 


Local copy | *Local copy 


Local copy 


YES 


Expressions *Local copy 


*YES 


Array elements 


Virtual array elements Local copy 
YES 


NO 


*Local copy 
*YES 
NO 


Entire arrays 


Entire virtual arrays 


* One asterisk indicates the default parameter passing mechanisms for 
BASIC programs. 


*" Two asterisks indicate that the value can have 32 bits, at most. 
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Table 20: BASIC—PLUS—2 Parameter Passing Mechanisms 


Argument Type BY VALUE | __ BY REF BY DESC 


Numeric Arguments 


Variables 

Constants 

Expressions 

Array elements 
Virtual array elements 
Entire arrays 

Entire virtual arrays 
String Arguments 
Variables 

Constants 

Expressions 

Array elements 
Virtual array elements 


Entire arrays 


Entire virtual arrays 


*YES 
*Local copy 
*Local copy 
*Local copy 
*Local copy 

YES 

NO 


YES 
Local copy 
Local copy 
Local copy 
Local copy 

YES 

NO 


*YES 
*Local copy 
*Local copy 
*Local copy 
*Local copy 

*YES 

*YES 


* One asterisk indicates the default parameter passing mechanisms for 
BASIC programs. You should never use a BY clause when calling a BASIC 


cuibnen gram fear 2 BASIC tote tt at eater oot ea 
SUMPIVEI aii WUT a AAOI Talli Prusialil. 


™ Two asterisks indicate that the value can be only WORD or BYTE. Other 
data types require more than the 16 bits of storage allowed. 


Note 


DIGITAL recommends that you not pass entire virtual arrays as parameters in the CALL 
statement. Instead, you can share the data in a virtual array between a calling program 
and a subprogram by opening a virtual file in either program and dimensioning the 
array (using the same channel number) in both programs. 
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2.0 CHAIN 


Note 


The CHAIN statement is not recommended for new program development. DIGITAL 
recommends that you use the CALL statement for program segmentation. 


Function 


The CHAIN statement transfers control from the current program to an executable BASIC program. 
CHAIN closes all files, then requests that the new program begin execution. Control does not return 
to the original program when the new program finishes executing. 


Format 


General 
CHAIN str-exp 


BASIC—PLUS-2 on RSTS/E only 


CHAIN str-exp [ LINE lin-num ] 


Syntax Rules 


1. Str-exp represents the file specification of the program to which control is passed. It can be 
a quoted or unquoted string. 


® Str-exp must refer to an executable image or BASIC signals an error. 


e lf you do not specify a file type, VAX—11 BASIC searches for an EXE file type and 
BASIC—PLUS—2 searches for a TSK file type. 


e You cannot chain to a program on another node. 
BASIC—PLUS—2 


1. On RSTS/E systems you can specify that control pass to a specified line number in another 
BASIC—PLUS—2 program. 


e Lin-num specifies a line in another BASIC program. It must be in the range 1 to 32767, 
inclusive. 


e If you specify a lin-num, the program to which control passes must have been compiled 
with the /CHAIN qualifier. The /CHAIN qualifier overrides the /NOLINE qualifier. 


General Rules 


1. Execution starts at the first line number of the specified program unless your system is 
RSTS/E and you have specified a lin-num at which execution is to start. 


2. On RSTS/E systems, BASIC—PLUS—2 signals an error when the specified line number does 
not exist. 
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ining takes place, al! active outout buffers (except terminal-format files) are 
written, all open files are closed, and all storage is released. On RSTS/E systems, the last 
buffer (512 bytes) of a terminal-format file does not get written unless the file is closed 
before the CHAIN statement executes. 


(2 
Cc 
a 
¢ 
cq) 
C ‘ 
o 
ga 


4. Because a CHAIN statement passes control from the executing image, the values of any 
program variables are lost. This means that you can pass parameters to a chained program 
only by using files or a system-specific feature such as the GET/PUT Core Common on 
RSTS/E systems, or LIB$GET and LIB$PUT on VMS systems. 


5. See BASIC on RSTS/E Systems or BASIC on RSX-11M/M-—PLUS Systems for information 
about how the CHAIN statement is implemented on your system. 


Examples 

General 

i0a CHAIN "PROG2" 
900 CHAIN PROGS.EXE 


BASIC—PLUS—2 on RSTS/E only 


200 CHAIN PROGA.TSK LINE 300 
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CHANGE 


3.0 CHANGE 


Function 


The CHANGE statement: 1) converts a string of characters to their ASCII integer values or 2) converts 
a list of numbers to a string of ASCII characters. 


Format 


String Variable to Array 
CHANGE str-exp TO num-array 


Array to String Variable 


CHANGE num-array TO str-vbl 


Syntax Rules 


1. Num-array should be a one-dimensional array (or list). If you specify a two-dimensional 
array, BASIC converts only the zero row of that array. BASIC does not support CHANGE to 
or from arrays of more than two dimensions. 


2.  Str-exp is a string expression. 


WwW 


VAX-11 BASIC does not support RECORD elements as a destination string or as a source 
or destination array for the CHANGE statement. 


Genera! Rules 
String Variable to Array 
1. This format converts each character in str-exp to its ASCII value. 
2. BASIC assigns the value of str-exp’s length to the zero element (0) or (0,0) of the num-array. 


3. BASIC assigns the ASCII value of the first character in str-exp to the first element, (1) or 
(0,1), of num-array, the ASCII value of the second character to the second element, (2) or 
(0,2), and so on. 


4. If the string is longer than the bounds of num-array, BASIC does not translate the excess 
characters, and signals the error ‘‘subscript out of range’ (ERR=55). Element zero, (0) or 
(0,0), of num-array still contains the length of str-exp. 


Array to String Variable 
1. This format converts the elements of num-arr to a string of characters. 


2. The length of str-vb/ is determined by the value in the zero element, (0) or (0,0), of 
num-array. lf the value of element zero is greater than the array bounds, BASIC signals the 
error ‘subscript out of range’ (ERR=55). 
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3. BASIC changes the first element, (1) or (0,1), of num-array to its ASCII character equiva- 
lent, the second element, (2) or (0,2), to its ASCIi equivalent, and so on. The length of the 
returned string is determined by the value in the zero element of num-array. For example, 
if num-arr is dimensioned as (10), but the zero element (0) contains the value 5, BASIC 
changes only elements (1), (2), (3), (4), and (5) to string characters. 


4. BASIC truncates floating-point values to integers before converting them to characters. 
5. Values in array elements are treated modulo 256. 

Examples 

String Variabie to Array 


30 DIM ARRAY ~CHANGESZ(6) 
60 CHANGE "“ABCDE" TO ARRAY _CHANGES% 


Array to String Variable 


200 CHANGE ARRAY CHANGESZ TO AS 
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4.0 CLOSE 


Function 


The CLOSE statement ends I/O processing to a device or file on the specified channel. 


Format 


CLOSE chni-exp.... . 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
can be preceded by an optional pound sign (#). 


General Rules 


1. BASIC writes the contents of any active buffers to the file or device before it closes that file 
or device. 


2. Channel 0 (the controlling terminal) cannot be closed. An attempt to do so has no effect. 


3. If you close a magnetic tape file that is open FOR OUTPUT, BASIC writes an end-of-file on 
the magnetic tape. 


4. If you try to close a channel that is not currently open, BASIC does not signal an error and 
the CLOSE statement has no effect. 


Examples 


1000 CLOSE #1, 3 


138 BASIC Reference Manual 


COMMON 


Function 


The COMMON statement defines a named, shared storage area called a COMMON block or pro- 
gram section (PSECT). BASIC program modules can access the values stored in the COMMON by 
specifying a COMMON with the same name. 


Format 


[ET 


COM 
COMMON [ ( com-nam ) ] { [ data-type ] com-item }.... 


com-item: num-unsubs-vbl-nam 
num-array-nam ( int-const,... ) 
str-unsubs-vbl-nam = int-const 


str-array-nam ( int-const,... ) [ = int-const ] 
FILL [ ( int-const ) ][ = int-const ] 

FILL% [ ( int-const ) ] 

FILL$ [ ( int-const ) ] [ = int-const ] 


Syntax Rules 
1. Com-nam is optional. If present, it must be in parentheses. 


2. A COMMON can have the same name as a program variable. However, in 
BASIC—PLUS—2, a COMMON cannot have the same name as a subprogram within the 
same task image. 


A COMMON and a MAP in the same program module cannot have the same name. 


4. Com-item declares the name and format of the data to be stored. 


¢ Num-unsubs-vbl-nam and num-arr-nam specify a numeric variable or a numeric array. 


@ Str-unsubs-vbI-nam and str-arr-nam specify a fixed-length string variable or array. You 
can specify the number of bytes to be reserved for the variable with the =int-const 
clause. The default string length is 16. 


e The FILL, FILL%, and FILL$ keywords allow you to reserve parts of the record buffer 
within or between data elements and to define the format of the storage. Int-const speci- 
fies the number of FILL items to be reserved. The = int-const clause allows you to specify 
the number of bytes to be reserved for string FILL items. Table 21 describes FILL item 
format and storage allocation. 
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Note 


rin 


in the applicable formats of FILL, (int-const) represents a repeat count, not an 
array subscript. FILL (n) represents n elements, not n + 1. 


Data-type can be any BASIC data-type keyword or, in VAX—11 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manual. 


ea 


6. When you specify a data-type, all following com-items, including FILL items, are of that 
data type until you specify a new data type. 


7. lf you do not specify any data-type, com-items take the current default data type and size. 


~ 


Variable names, array names, and FILL items following a data-type cannot end in a dollar 
sign or percent sign character. 


9. Variables and arrays declared in a COMMON statement cannot be declared elsewhere in 
the program by any other declarative statements. 


10. COMMON elements must be separated with commas. 


VAX-11 BASIC 


1. The default com-nam is “$BLANK’’. 


2. Com-nam can consist of from 1 to 31 characters. The first character of the name must be 
an alphabetic character (A through Z). The remaining characters, if present, can be any 
combination of letters, digits (0 through 9), dollar signs ($), periods (.), or underscores (_). 


BASIC-PLUS—2 
1. The default com-nam is “.$$$$.”’. 


2. Com-nam can consist of from one to six characters. The first character must be an alpha- 
betic character (A through Z). The remaining characters, if present, can be any combina- 
tion of letters, digits (0 through 9), dollar signs ($), or periods (.). 
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Table 21: FILL Item Formats and Storage Allocations 


FILL Format Storage Allocation 


Allocates storage for one floating-point element unless preceded by a data-type; the 
number of bytes allocated depends on the default floating-point data size or the speci- 
fied data-type. 


Allocates storage for the number of floating-point elements specified by int-const unless 
preceded By. a data- eye gis number of oe auceaten for each element depends on the 


FILL(int-const) 


FILL% Allocates storage for one integer element; the number of bytes allocated depends on the 
default integer size. 


FILL%(int-const) Allocates storage for the number of integer elements specified by int-const; the number 
of bytes allocated for each element depends on the default integer size. 


FILL$ Allocates 16 bytes of storage for a string element. The dollar sign can be omitted if the 


FILL keyword is preceded by the STRING data-type. 


Allocates 16 bytes of storage for the number of string elements specified by int-const. 
The dollar sign can be omitted if the FILL keyword is preceded by the STRING data-type. 


FILL$(int-const) 


FILL$ =int-const Allocates the number of bytes of storage specified by =int-const for a string element. 


The dollar sign can be omitted if the FILL keyword is preceded by the STRING data-type. 


Allocates the number of bytes of storage specified by = int-const for the number of string 
elements specified by int-const. The dollar sign can be omitted if the FILL keyword is 
preceded by the STRING data-type. 


FILL${int-const) = int-const 


Note 


In the applicable formats of FILL, (int-const) represents a repeat count, not an 
array subscript. FILL (n) represents n elements, not n + 1. 


General Rules 


1. A COMMON area and a MAP area with the same name, in different program modules, 
specify the same storage area. 


2. BASIC does not execute COMMON statements. The COMMON statement allocates and 
defines the data storage area at compile time. 


3. When you link or task-build your program, the size of the COMMON area is the size of the 
largest COMMON area with that name. That is, BASIC concatenates COMMON state- 
ments with the same com-nam within a single program module into a single PSECT. The 
total space allocated is the sum of the space allocated in the concatenated COMMON 
statements. 


4. The COMMON statement must lexically precede any reference to variables declared in it. 


5. A COMMON area can be accessed by more than one program module, as long as you 
define the com-nam in each module that references the COMMON. 
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10. 


Examples 


300 


Variable names ina COMMON statement in one program module need not match those in 
another program module. 


VAX—11 BASIC does not initialize variables in COMMON blocks. 


Since BASIC—PLUS—2 initializes variables in COMMON blocks, you must use unique 
names for each variable in each COMMON block. 


In BASIC—-PLUS—2, you should know how your program overlays if data stored in a 
COMMON area is to be shared by several program modules. The COMMON should be 
named in an overlay unit that will remain in memory as long as program units need to 
reference the COMMON data. If the overlay that names the COMMON is forced out of 
memory, BASIC reinitializes the COMMON area to zero when the overlay is brought back 
into memory. See BASIC on RSX—11M/M-—PLUS Systems or BASIC on RSTS/E Systems for 
information on overlay structures. 


The data-type specified for com-items or the default data type and size determines the 
amount of storage reserved in a COMMON block: 


e BYTE integers reserve 1 byte. 

@ WORD integers reserve 2 bytes. 

e LONG integers reserve 4 bytes. 

e SINGLE floating-point numbers reserve 4 bytes. 

¢ DOUBLE floating-point numbers reserve 8 bytes. 

@ GFLOAT floating-point numbers reserve 8 bytes (VAX—11 BASIC only). 

@ HFLOAT floating-point numbers reserve 16 bytes (VAX—11 BASIC only). 

@ DECIMAL(d,s) packed decimal numbers reserve (d+ 1)/2 bytes (VAX—11 BASIC only). 


e STRING reserves 16 bytes (the default) or the number of bytes you specify with 
= int-const. 


COMMON (INYEN) INTEGER SHELF.NUMBER: STRING ROW = Zs & 
DOUBLE FILL+ PART.BIN» LISTPRICE 
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Function 


DATA 


The DATA statement creates a data block for the READ statement. 


Format 


num-lit 
DATA str-lit 


oll 


Syntax Rules 


ie 
ze 


“I 


Num-lit specifies a numeric literal. 


Str-lit is a character string that starts and ends with double or single quotation marks. The 
quotation marks must match. 


Ung-str is a character sequence that does not start and end with double or single quotation 
marks and does not contain a comma. 


Commas separate data elements. If a comma is part of a data item, the entire item must be 
enclosed in quotation marks. 


Because BASIC treats comment fields in DATA statements as part of the DATA sequence, 
do not include comments. 


A DATA statement must be the last or the only statement on a line. 


INATA ctart. + 1 1 i ‘ 
DATA statements must end with a line terminator. BASIC interprets all characters except 


the ampersand (&) between the keyword DATA and the final line terminator as part of the 
data. You can continue DATA statements by placing an ampersand (&) immediately before 
the line terminator. 


You cannot use the percent sign suffix for integer constants that appear in DATA state- 
ments. An attempt to do so causes BASIC to signal ‘‘Data format error’ (ERR=50) when 
you try to run the program. 


General Rules 


1. 
2. 


DATA statements are local to a program module. 


BASIC does not execute DATA statements. Instead, BASIC passes control to the next exe- 
cutable statement. 


A program can have more than one DATA statement. BASIC assembles data from all DATA 
statements in a single program unit into a lexically ordered single data block. 


BASIC ignores leading and trailing blanks and tabs unless they are in a string literal. 
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5. Commas are the only valid data delimiters. You must use a quoted string literal if the 
comma is to be part of a string. 


6. BASIC ignores DATA statements without an accompanying READ statement. 


7. BASIC signals the error ‘‘Data format error’’ if the DATA item does not match the data type 
of the variable specified in the READ statement or if a data element that is to be read into 
an integer variable ends with a percent sign (%). If a string data element ends with a dollar 
sign ($), BASIC treats the dollar sign as part of the string. 

Examples 


300 DATA 35+ 32.3% PRODUCTION SEQUENCE, ‘SYSTEM’: ‘1:2’ 
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7.0 DEC 


Function 


The DECLARE statement explicitly assigns a data type to and names a variable, an entire array, a 
function, or a constant. 


Format 


| Variables | 


DECLARE data-type decl-item [, [ data-type ] decl-item ]... 
DEF Functions 

DECLARE data-type FUNCTION { def-nam [ ( [ def-param ],... ) ] }.... 
Named Constants 


DECLARE data-type CONSTANT { const-nam = const }.... 


decl-item: unsubs-vbl-nam 


array-nam ( int-const.... ) 


def-param: [ data-type ] 


Syntax Rules 
i. Data-type can be any BASIC data-type keyword or, in VAX—117 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manual. 
Variables 
1. Decl-item names a variable or an array. 


2. A decl-item cannot end in a percent sign (%) or dollar sign ($). 


3. A decl-item named in a DECLARE statement cannot also be named in another DECLARE 
statement, or a DEF, EXTERNAL, FUNCTION, SUB, COMMON, MAP, or DIM statement. 


4. Int-const specifies the upper bounds of the array-nam. 


5. Each decl-item is associated with the preceding data-type. A data-type is required for the 
first decl-item. 


6. Decl-items of data-type STRING are dynamic strings. 
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DEF Functions 


1. 
2: 
3: 


yr 


Def-nam names the DEF function. It cannot end with a percent sign (%) or dollar sign ($). 
Data-type specifies the data type of the value the function returns. 


Def-params specify the number and, optionally, the data-type of the DEF parameters. 
Parameters define the arguments the DEF expects to receive when invoked. 


e When you specify a data-type, all following parameters are of that data type until you 
specify a new data type. 


e If you do not specify any data-type, parameters take the current default data type and 
size. 


e The number of parameters equals the number of commas plus one. For example, empty 
parentheses specify one parameter of the default type and size; one comma inside the 
parentheses specifies two parameters of the default type and size, and so on. One 
data-type inside the parentheses specifies one parameter of the specified data type; two 
data-types separated by one comma specifies two parameters of the specified type, and 
sO on. 


Named Constants 


1. 
2, 


ee 
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Const-nam is the name you assign to the const. 


Data-type specifies the data type of the const-nam. The value of the const must be numeric 
if the data type is numeric and string if the data type is STRING. If the data-type is STRING, 
const must be a quoted string or another string constant. 


Const cannot end with a percent sign (%) or a dollar sign ($). 
Const cannot be of the RFA data type. 

For VAX~11 BASIC, string constants cannot exceed 498 characters. 
For BASIC—PLUS—2, string constants cannot exceed 128 characters. 


VAX-11 BASIC allows const to be an expression for all data types except DECIMAL. 
Expressions are not allowed as values when you name DECIMAL constants. 


BASIC—PLUS—2 allows const to be an expression for STRING and INTEGER data types. 
Expressions are not allowed as values when you name floating-point constants. 


Allowable operators in DECLARE CONSTANT expressions include all valid arithmetic, 
relational, and logical operators except exponentiation. Built-in functions cannot be used in 
DECLARE CONSTANT expressions. The following examples use valid expressions as 
values: 


100 DECLARE DOUBLE CONSTANT MAX_VALUE = (PI 7/2) (VAX-17 BASIC only) 
100 DECLARE STRING CONSTANT LEFT_ARROW = (’4----- i+ LEO + ER) 
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Genera! Rules 

1. The DECLARE statement is not executable. 

2. The DECLARE statement must lexically precede any reference to the variables, functions, 
or constants named in it. 

3. You cannot declare virtual arrays. 

4. To avoid confusion and to retain BASIC’s implicit data typing feature, variable names 
ending with a dollar sign or percent sign are invalid in a DECLARE statement. 

Variables 

1. Variables named in a DECLARE statement are initialized to zero if numeric or to the null 
string if string. 

2. Subsequent decl-items are associated with the specified data type until you specify another 


data-type. 


DEF Functions 


1. 


The DECLARE FUNCTION statement allows you to name a function defined in a DEF 
statement, specify the data type of the value the function returns, and declare the number 
and data type of the DEF parameters. 


Data-type keywords must be separated by commas. For example: 


100 DECLARE DOUBLE FUNCTION INTEREST( + sDOUBLE +SINGLE) 


This example decares two parameters of the default type and size, one DOUBLE parame- 
ter, and one SINGLE parameter for the function named INTEREST. 


The first specification of a def-param is the default for subsequent arguments until you 
specify another def-param. 


Named Constants 


1. 


The DECLARE CONSTANT statement allows you to name a constant value and assign a 
data type to that value. Note that you can specify only one data type in a DECLARE 
CONSTANT statement. To declare another constant, you must use a second DECLARE 
CONSTANT statement. 


You cannot change the value assigned to const-nam. 


You cannot use a const-nam where a variable is required. 
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Examples 


Variables 


100 


In VAX-11 BASIC, the specified data-type determines the data type of const. For example: 
100 DECLARE WORD CONSTANT MMM 


Q 
1.5 


200 DECLARE REAL CONSTANT 222 = 123% 
300 DECLARE BYTE CONSTANT YY = '123°L 
400 PRINT MMM +222 s5YYY 
RUNNH 

i 1223 123 


In this example, BASIC truncates the value 1.5 to a WORD integer, and ignores the percent 
suffix and the L (LONG) data type. 


BASIC—PLUS-2 signals the error ‘Constant is inconsistent with the type of <name> ”’ if the (ap2) 
data type of const does not match the specified data-type. 


Note 


Data types specified in a DECLARE statement override any defaults specified in 
COMPILE command qualifiers or OPTION statements. 


DECLARE INTEGER CATALOG_NUM+ DOUBLE PRICE,» STRING ITEM_NAME 


DEF Functions 


100 


DECLARE INTEGER FUNCTION AMOUNT( > +DOUBLEsBYTE: +) 


Named Constants 


100 
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DECLARE DOUBLE CONSTANT INTEREST_RATE = 15.22 
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8.0 DEF 


Function 


The DEF statement lets you define a single- or multi-line function. 


Format 


Single-Line DEF 


DEF [ data-type ] def-nam [ ( [ [ data-type ] unsubs 


Multi-Line DEF 
DEF [ data-type ] def-nam [ ( [ [ data-type ] unsubs-vbi-nam ],... ) ] 
[ statement ]... 


END DEF 
FNEND 


Syntax Rules 


1. Data-type can be any BASIC data-type keyword or, in VAX-11 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manual. 


2. The data-type that precedes the def-nam specifies the data type of the value returned by the 
DEF function. 


3. Def-nam is the name of the DEF function. The def-nam may contain from 1 to 31 
characters. 


4. lf the def-nam also appears in a DECLARE FUNCTION statement, the following rules 
apply: 
e A function data-type is required. 


e The first character of the def-nam must be an alphabetic character (A through Z). The 
remaining characters may be any combination of letters, digits (0 through 9), dollar signs 
($), underscores (_), or periods (.), with one restriction: the last character cannot be a 
dollar sign. 


5. If the def-nam does not appear in a DECLARE FUNCTION statement, but the DEF state- 
ment appears before the first reference to the def-nam, the following rules apply: 


e The function data-type is optional. 


@ The first character of the def-nam must be an alphabetic letter (A through Z). The remain- 
ing characters can be any combination of letters, digits, dollar signs, underscores, or 


periods. (continued on next page) 
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9: 


10. 


e If a function data-type is specified, the last character in the def-nam cannot be a dollar 
sign or percent sign. 


e If a function data-type is not specified, the last character in the def-nam must be a 
percent sign (%) for an INTEGER function, a dollar sign ($) for a STRING function, or a 
letter, digit, period, or underscore for a function of the default type and size. 


If the def-nam does not appear in a DECLARE FUNCTION statement, and the DEF state- 
ment appears after the first reference to the def-nam, the following rules apply: 


© The function data-type cannot be present. 


© The first two characters of the def-nam must be FN. The remaining characters can be any 
combination of letters, digits, dollar signs, underscores, or periods, with one restriction: 
the last character must be a percent sign (%) for an INTEGER function, a dollar sign ($) 
for a STRING function, or a letter, digit, period, or underscore for a function of the 
default type and size. 


@ There must be at least one character between the FN characters and the ending dollar 


sign or percent character. FN$ and FN% are not valid function names. 


Unsubs-vbI-nam specifies optional formal DEF parameters. Because the parameters are 
local to the DEF function, any reference to these variables outside the DEF body creates a 
different variable. 


You can specify the data-type of DEF parameters with a data-type keyword or, in VAX—11 
BASIC, with a data type defined in a RECORD statement. If you do not include a data type, 
the parameters are of the default type and size. Parameters that follow a data-type keyword 
are of the specified type and size until you specify another data type. 


BASIC—PLUS-—2 allows you to specify up to eight parameters in a DEF statement. 


VAX—11 BASIC allows you to specify up to 255 parameters in a DEF statement. 


Single-Line DEF 


1. 


Exp specifies the operations the function performs. 


Multi-Line DEF 
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Statements specify the operations the function performs. 
The END DEF or FNEND statement is required to end a multi-line DEF. 


You can use any BASIC statement except END FUNCTION, END SUB, FUNCTION, 
FUNCTIONEND, FUNCTIONEXIT, DEF, or DEF* in a function definition. 
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10. 


11. 


12. 


13: 


DEF 


When BASIC encounters a DEF statement, control of the program passes to the next exe- 
cutable statement after the DEF. 


Functions are invoked when you use the function name in an expression. 


You cannot specify how parameters are passed. When you invoke a function, BASIC 
evaluates parameters from left to right and passes parameters to the function so that they 
cannot be modified. Numeric parameters are passed BY VALUE and string parameters are 
passed BY DESC, where the descriptor points to a local copy. DEF functions may reference 
variables in the main program, but they cannot reference variables in other DEF or DEF* 
functions. A DEF function may, therefore, modify other variables in the program, but not 
variables within another DEF function. 


A DEF is local to the program or subprogram that defines it. 


The DEF statement, or the first invocation of a function, whichever occurs first, constitutes 
the declaration of the function. The DECLARE FUNCTION statement defines the name of 
the function, but does not invoke it. 


lf your program invokes a function with a name that does not start with FN before the DEF 
statement defines the function, or if the number of parameters, types of parameters, or type 
of result declared in the invocation disagree with the number or types of parameters 
defined in the DEF statement, BASIC signals an error. 


DATA statements in a multi-line DEF ar 
program module containing the function 


not local to the function; they are local to the 


e 
Al afinit 
UCTIENEL 


vot a 
I 


ion. 


The function value (that is, the location storing the value the function returns) is initialized 
to zero or the null string each time you invoke the function. 


ON ERROR GO BACK is the default error handler in a DEF function definition. 


ON ERROR statements within a DEF are local to the function. 


A GOTO, GOSUB, ON ERROR GOTO, or RESUME statement in a multi-line function 
definition must refer to a line number or label in the same function definition. 


You cannot transfer control into a multi-line DEF except by invoking the function. 


DEF functions can be recursive. 
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Examples 
Single-Line DEF 


1000 


DEF DOUBLE ADD (DOUBLE A» B+ SINGLE C>+ D; E) 
2000 INPUT ‘Enter five numbers to be added’iUsWoXs 
2010 PRINT ‘The sum is’sADD(U sWeX +¥ 92) 


Multi-Line DEF 


1000 DEF DOUBLE PAYROLL(INTEGER HOURS, REAL RATE) 
EXIT GEF IF HOURS = 90 
DECLARE INTEGER OVERTIME 
OVERTIME = HOURS - 40 2 
IF OVERTIME <= O 
THEN HOURS = HOURS 
ELSE HOURS = 40 
END IF 
DECLARE REAL CONSTANT OGVER_RATE = 1.5 
PAYROLL = (HOURS * RATE) + (OVERTIME #* 
10306 END DEF 
1040 INPUT "Your hours this week" SMY_HOURS 
1045 INPUT "Your Pay rate"3MY_PAY_RATE 
1050 PRINT ‘Your Pay for the week 
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(QVER_LRATE * RATE)) 


is’ PAYROLL (MY HOURS +MY_PAY_RATE) 


DEF* 


9.0 DEF* 


Function 


The DEF* statement lets you define a single- or multi-line function. 


Note 


The DEF* statement is not recommended for new program development. DIGITAL 
recommends that you use the DEF statement for defining single- and multi-line 
functions. 


Format 


Single-Line DEF* 


DEF* [ data-type ] def-nam [ ( [ [ data-type ] unsubs-vbl-nam ],... ) ] = exp 


Multi-Line DEF« 


DEF* [ data-type ] def-nam [ ( [ [ data-type ] unsubs-vbl-nam ],... } } 


{ statement ]... 


END DEF 
FNEND 


Syntax Rules 


1. Data-type can be any BASIC data-type keyword or, in VAX—11 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manual. 


2. The data-type that precedes the def-nam specifies the data type of the value returned by the 
DEF* function. 


3. Def-nam is the name of the DEF* function. The def-nam may contain from 1 to 31 
characters. 


4. If the def-nam also appears in a DECLARE FUNCTION statement, the following rules 
apply: 
e A function data-type is required. 
@ The first character of the def-nam must be an alphabetic character (A through Z). The 
remaining characters may be any combination of letters, digits (0 through 9), dollar signs 


($), underscores (_), or periods (.), with one restriction: the last character cannot be a 
dollar sign. 
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5. If the def-nam does not appear in a DECLARE FUNCTION statement, but the DEF* state- 
ment appears before the first reference to the def-nam, the following rules apply: 


@ The function data-type is optional. 


e The first character of the def-nam must be an alphabetic letter (A through Z). The remain- 
ing characters can be any combination of letters, digits, dollar signs, underscores, or 
periods. 


e If a function data-type is specified, the last character in the def-nam cannot be a dollar 
sign or a percent sign. 


e lf a function data-type is not specified, the last character in the def-nam must be a 
percent sign (%) for an INTEGER function, a dollar sign ($) for a STRING function, or a 
letter, digit, period, or underscore for a function of the default type and size. 


6. If the def-nam does not appear in a DECLARE FUNCTION statement, and the DEF* state- 
ment appears after the first reference to the def-nam, the following rules apply: 


@ The function data-type cannot be present. 


® The first two characters of the def-nam must be FN. The remaining characters can be any 
combination of letters, digits, dollar signs, underscores, or periods, with one restriction: 
the last character must be a percent sign (%) for an INTEGER function, a dollar sign ($) 
for a STRING function, or a letter, digit, period, or underscore for a function of the 
default type and size. 


® There must be at least one character between the FN characters and the ending dollar 
sign or percent character. FN$ and FN% are not valid function names. 


7. Unsubs-vbl-nam specifies optional formal function parameters. 


8. You can specify the data-type of function parameters with a data-type keyword. If you do 
not specify a data-type, parameters are of the default type and size. Parameters that follow 
a data-type keyword are of the specified type and size until you specify another data-type. 


9. BASIC—PLUS—2 allows you to specify up to eight parameters in a DEF* statement. 
10. VAX—11 BASIC allows you to specify up to 255 parameters in a DEF* statement. 
Single-Line DEF* 

1. Exp specifies the operations the function performs. 

Multi-Line DEF* 
1. Statements specify the operations the function performs. 
2. The END DEF or FNEND statement is required to end a multi-line DEF*. 


3. You can use any BASIC statement except END FUNCTION, END SUB, FUNCTION, 
FUNCTIONEND, FUNCTIONEXIT, DEF, or DEF* in a function definition. 
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Generai Ruies 


i 


11. 


12, 


When BASIC encounters a DEF* statement, control of the program passes to the next 
executable statement after the DEF. 


Functions are invoked when you use the function name in an expression. 


You cannot specify how parameters are passed. When you invoke a DEF* function, 
BASIC evaluates parameters from left to right and passes parameters to the function so that 
they cannot be modified. Numeric parameters are passed BY VALUE, and string 
parameters are passed BY DESC, where the descriptor points to a local copy. DEF* 
functions may reference Variables in the main program, but they cannot reference 
variables in other DEF or DEF* functions. A DEF* function may, therefore, modify varia- 
bles in the program, but not variables within another DEF* function. 


A DEF* is local to the program or subprogram that defines it. 


The DEF* statement permits inclusion of the GOTO, ON GOTO, GOSUB, and 
ON GOSUB statements in a multi-line DEF* function. This allows you to transfer pro- 
gram control outside the function definition. 


Although other variables used within the body of a DEF* are not iocal to the DEF*, DEF* 
formal parameters are. However, if you change the value of formal parameters within a 
DEF* function and then transfer control out of the DEF* without executing the END DEF 
or FNEND statement, variables outside the DEF* that have the same names as DEF* 
formal parameters are also changed. 


The DEF* statement, or the first invocation of a function, whichever occurs first, consti- 
tutes the declaration of the function. The DECLARE FUNCTION statement defines the 
name of the function, but does not invoke it. 


rime f 


If your program invokes a function before the DEF* statement defines the function, or if 
the number of parameters, types of parameters, or type of result declared in the invoca- 
tion disagree with the number or types of parameters defined in the DEF* statement, 
BASIC signals an error. 


DEF* function values are not initialized when DEF* functions are invoked. Therefore, if a 
DEF* is invoked, and no new function value is assigned, the DEF* returns the value of its 
previous invocation. 


DEF* functions can be recursive. 


DATA statements in a multi-line DEF* are not local to the function; they are local to the 
program module containing the function definition. 


The error handler of the program module that contains the DEF* is the default error 
handler for a DEF* function, not ON ERROR GO BACK as in DEF functions. Parameters 
return to their original values when control passes to the error handler. 
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Examples 
Single-Line DEF* 
1000 


2000 
2010 


INPUT 


Multi-Line DEF* 


19000 DEF*# DOUBLE EXAMPLE(DOUBLE A+ B;+ SINGLE C, 
’ EXIT DEF IF B = 0 
EXAMPLE = (A/B) + C - (DE) 
1030 END DEF 
1040 INPUT ‘Enter 5 numbers’ sUoW eK e¥oZ 
1050 PRINT EXAMPLE (Y sWoX 9% +2) 


DEF* STRING CONCAT(STRING A+B) = A + B 


‘Enter two words’ SWORDI »WORD2 


PRINT CONCAT(WORD1 +>WORD2) 
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DELETE 


10.0 DELETE 


Function 


The DELETE statement removes a record from a relative or indexed file. 


Format 


DELETE chnl-exp 


Syntax Rules 
1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


General Rules 


1. The DELETE statement removes the current record from a file. You cannot then access the 
record. 


2. The file specified by chni-exp must be open with ACCESS MODIFY or WRITE. 


3. You can delete a record only if the last |/O statement executed on the specified channel! 
was a successful GET or FIND. 


4. The DELETE statement leaves the Current Record Pointer undefined and the Next Record 
Pointer unchanged. 


5. BASIC signals an error when the 1/O channel is illegal or not open, when no current record 
exists, when access is illegal or illogical, when the operation is illegal, or when the record 
or bucket is locked. 


6. In VAX—11 BASIC, if the record being deleted is in a file opened with UNLOCK EXPLICIT, 
the DELETE statement does not remove the lock on the record. If no lock was imposed with 
a previous GET or FIND statement, the default lock, ALLOW NONE, remains imposed. 
The lock can be removed with the FREE or UNLOCK statement. See the sections on GET, 
FIND, OPEN, FREE, and UNLOCK in this manual for more information on explicit record 
locking and unlocking. 


Examples 


1000 DELETE 5 
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11.0 DIMENSION 


Function 


The DIMENSION statement creates and names a static, dynamic, or virtual array. The array subscripts 
determine the dimensions and size of the array. You can specify the data type of the array and 
associate the array with an I/O channel. 


Format 


Nonvirtual, Nonexecutable 


DIM 
DIMENSION { [ data-type ] array-nam ( int-const,... ) }.... 


Virtual 


DIM 


DIMENSION chnl-exp, { [ data-type ] array-nam ( int-const,... ) [ = int-const ] }.... 


Executable 


DIM 
DIMENSION { [ data-type ] array-nam ( int-vbl,... ) },... 


Syntax Rules 
1. Array-nam is an array name. It must conform to the rules for naming variables. 


2. An array-nam in a DIM statement cannot also appear in a COMMON, MAP, or DECLARE 
statement. 


3. Data-type can be any BASIC data-type keyword or, in VAX—11 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manual. 


4. If you do not specify a data type, the array-nam determines the type of data the array holds. 
If the array-nam ends in a percent sign (%), the array stores integer data. If the array-nam 
ends in a dollar sign ($), the array stores string data. Otherwise, the array stores data of the 
default type and size. 


5. A VAX—11 BASIC array can have up to 32 dimensions. 


6. A BASIC—PLUS—2 array can have up to eight dimensions. 
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Each instance of int-const or int-vb/ within the parentheses specifies the upper bound of an 
array dimension. 


@ In VAX-11 BASIC, array bounds must be in the range 0 to 27". 
@ In BASIC-PLUS-—2, array bounds must be in the range 0 to 2’*". 


e Although the compiler does not generate an error for subscript values outside of these 
ranges, there is a limit to the amount of storage your system can allocate. Therefore, very 
large arrays can cause an internal allocation error or a run-time error. 


Nonvirtual, Nonexecutable 


1. When all the dimension specifications are int-consts, as in DIM A(15%,10%,20%), the 
DIM statement is nonexecutable and the array is static. A static array cannot appear in 
another DIM statement because BASIC allocates storage at compile time. 

2. Anonexecutable DIM statement must lexically precede any reference to the array it dimen- 
sions. That is, you must DIMENSION a static array before you can reference array 
elements. 

Virtual 

1. The pound sign (#) must precede chnl-exp when dimensioning virtual arrays. 

2. The virtual array must be dimensioned and the file must be open before you can reference 
the array. 

3. When the data-type is STRING, the =int-const clause specifies the length of each array 
element. The default string length is 16 characters. Virtual string array lengths are rounded 
to the next higher power of two. 

Executable 


When any of the dimension specifications are int-vbls, as in DIM A(10%,20%,Y%), the 
DIM statement is executable and the array is dynamic. A dynamic array can be redimen- 
sioned with a DIM statement any number of times, since BASIC allocates storage at run 
time. 


General Rules 


1. 


You can create an array implicitly by referencing an array element without using a DIM 
statement. This causes BASIC to create an array with dimensions of (10), (10,10), 
(10,10,10), and so on, depending on the number of bounds specifications in the refer- 
enced array element. You cannot create virtual or executable arrays implicitly. 


The lower bound of a BASIC array is always zero, rather than one. Thus, A(10) allocates 11 
elements, A(10,10) allocates 121 elements, and A(0,0,0) allocates 1 element. 


BASIC allocates storage for arrays by row, from right to left. 
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Nonvirtual, Nonexecutable 


1. 


Virtual 
Te 


ie 


You can declare arrays with the COMMON, MAP, and DECLARE statements. Arrays so 


declared cannot be redimensioned with the DIM statement. Furthermore, string arrays 
declared with a COMMON or MAP statement are always fixed-length. 


If you reference an array element declared in an array whose subscripts are larger than the 
bounds specified in the DIM statement, BASIC signals the error ‘‘Subscript out of range” 
(ERR=55). 


When the rightmost subscript varies faster than the subscripts to the left, fewer disk 
accesses are necessary to access array elements in virtual arrays. 


Using the same DIM statement for multiple virtual arrays allocates all arrays in a single disk 
file. The arrays are stored in the order they were declared. 


Any program or subprogram can access a virtual array by declaring it in a virtual 
DIMENSION statement. For example: 


100 DIM #1+ A190) 
200 DIM #1+ B(10) 


In this example, array B overlays array A. You must, however, specify the same channel 
number, data types, and limits in the same order as they occur in the DIM statement that 
created the virtual array. 


BASIC stores a string in a virtual array by padding it with trailing nulls to the length of the 
array element. It removes these nulls when it retrieves the string from the virtual array. 


In BASIC—PLUS—2 on RSX—11M/M-—PLUS systems and in VAX—11 BASIC, the OPEN state- 
ment for a virtual array must include the ORGANIZATION VIRTUAL clause for the 
chnl-exp specified in the DIMENSION statement. 


BASIC does not initialize virtual arrays and treats them as statically allocated arrays. You 
cannot redimension virtual arrays. 


Refer to the BASIC User’s Guide for more information on virtual arrays. 


Executable 


1. 


You create an executable, dynamic array by using integer variables for array bounds as in 
DIM A(Y%,X%). This eliminates the need to dimension an array to its largest possible size. 
Array bounds in an executable DIM statement can be constants or variables, but not 
expressions. At least one bound must be a variable. 


You cannot reference an array named in an executable DIM statement until after the DIM 
statement executes. 


You can redimension a dynamic array to make the bounds of each dimension larger or 
smaller, but you cannot change the number of dimensions. That is, you cannot redimen- 
sion a four-dimensional array to be a five-dimensional array. 
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4. The executable DIM statement cannot be used to dimension virtual arrays, arrays-received 
as formal parameters, or arrays declared in COMMON, MAP, or nonexecutable DIM 
statements. 


5. An executable DIM statement always reinitializes the array to zero (for numeric arrays) or 
the null string (for string arrays). 


6. If you reference an array element declared in an executable DIM statement whose sub-. 
scripts are larger than the bounds specified in the last execution of the DIM, BASIC signals 
the error ‘Subscript out of range’” (ERR=55). 

Examples 


Nonvirtual, Nonexecutable 


300 DIM STRING NAME_LIST(100;100), BYTE AGE(100) 
Virtual 

100 DIM #1%+ STRING NAM_LIST(500),+ REAL AMOUNT(10+10) 
Executable 

200 DIM DOUBLE INVENTORY (BASE +»MARKUP) 
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12.0 END 


Function 


The END statement marks the physical and logical end of a main program, a program module, or a 
block of statements. 


Format 


END [ block ] 


DEF 
FUNCTION 
GROUP (VAX—11 only) 


RECORD (VAX—17 only) 
SELECT 

SUB 

VARIANT (VAX-17 only) 


_ Syntax Rules 


1. The END statement with no block keyword marks the end of a main program. The END 
statement must be the last statement on the lexically last line in the main program. 


2. The END statement followed by a block keyword marks the end of a BASIC SUB or 
FUNCTION subprogram, or a DEF, IF, or SELECT statement block. In VAX—11 BASIC, END 
RECORD, END GROUP, and END VARIANT mark the end of a RECORD statement, or a 
GROUP component or VARIANT component of a RECORD statement. 


3. The END block statement must be the lexically last statement in a subprogram or statement 
block and must match the statement that established the subprogram or statement block. 


General Rules 


1. When an END statement marking the end of a main program executes, BASIC closes all 
files and releases all program storage. 


2. BASIC cannot execute an END statement that marks the end of a program unit while an 
error is being handled. The module must execute a RESUME or ON ERROR statement 
before the END statement. 


3. BASIC signals an error when a program contains an END block statement with no corre- 
sponding and preceding block keyword. 


4. When BASIC executes an END DEF or END FUNCTION statement, it returns the function 
value to the statement that invoked the function and releases all storage associated with the 
DEF or FUNCTION. 
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restores the error handling in effect when the DEF was invoked. 


6. Error handlers set up in DEF* statements are global. The END DEF statement does not 
restore the error handling in effect when the DEF* was invoked. 


7. The END SUB and END FUNCTION statements do not affect |/O operations or files. 


8. The END SUB statement releases the storage allocated to local variables and returns con- 
trol to the calling program. 


9. The END SUB statement cannot be executed in an error handler unless the SUBEND is in a 
subprogram called by the error handler. 


Examples 


300 IF A = 26 
THEN PRINT "Bye" 
GOTQ 232767 
ELSE GOTO 100 
END IF ; 
i 


i 
32767 END 
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13.0 EXIT 


Function 


The EXIT statement lets you exit from a SUB or FUNCTION subprogram, a multi-line DEF, or from a 
statement block. 


Format 


EXIT block 


DEF 


FUNCTION 
SUB 
label 


Syntax Rules 


1. The FUNCTION, SUB, and DEF keywords specify the type of subprogram or multi-line 
DEF from which BASIC is to exit. 


2. Label specifies a statement label for an IF, SELECT, FOR, WHILE, or UNTIL statement 
block. 


General Rules 


1. An EXIT DEF, EXIT FUNCTION, or EXIT SUB statement is equivalent to an unconditional 
branch to an END DEF, END FUNCTION, or END SUB statement. Control then passes to 
the statement that invoked the DEF or to the statement following the statement that called 
the subprogram. 


2. The EXIT label statement is equivalent to an unconditional branch to the first statement 
following the end of the IF, SELECT, FOR, WHILE, or UNTIL statement labelled by the 
label. 


3. An error handler cannot execute an EXIT FUNCTION or EXIT SUB statement unless the 
error handler calls the FUNCTION or SUB subprogram. 


4. An EXIT FUNCTION or EXIT SUB statement cannot be used within a multi-line DEF 
function. 


5. When the EXIT FUNCTION or EXIT SUB statement executes, BASIC releases all storage 
allocated to local variables and returns control to the calling program. 
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3000 


6000 


10006 


LOOP_i: FOR 1% = 1% TO 16% 
PRINT 1% 
IF dee =-3e 
THEN EXIT LOOP_I 
END IF 

NEXT 1% 

i 

i 

i 

SUB SUBA 

i 

! 

EXIT SUB 

! 

H 

i 

END SUB 
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14.0 EXTERNAL 


Function 


The EXTERNAL statement declares constants, variables, functions, and subroutines external to your 
program. You can describe parameters for external functions and subroutines. 


Format 


External Constants 
EXTERNAL data-type CONSTANT const-nam.... 
External Variables 
EXTERNAL data-type unsubs-vbl-nam.... 
External Functions 
EXTERNAL data-type FUNCTION { func-nam [ pass-mech ] [ ( [ external-param ],... ) ] },... 


External Subroutines 


EXTERNAL SUB { sub-nam [ pass-mech ] [ ( [ external-param ],... ) ] }.... 
pass-mech: BY DESC 
BY REF 
| BY VALUE 


external-param: [ data-type ] [ DIM ({,]...) ] [ = int-const ] [ pass-mech ] 


Syntax Rules 


1. For external variables, data-type can be any valid numeric data type. 


2. For external constants, data-type can be: 


e For VAX—11 BASIC: BYTE, WORD, LONG, SINGLE, INTEGER (any size), or REAL (if 
the default size is SINGLE). 


e For BASIC—PLUS—2: WORD, or INTEGER (if the default size is WORD). 


3. For external functions and subroutines, data-type can be any BASIC data-type keyword 
or, in VAX—11 BASIC, a data type defined by a RECORD statement. Data-type keywords, 
size, range, and precision are listed in Table 2 in this manual. 
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In VAX—11 BASIC, the name of an external constant, variable, function, or subroutine can 
consist of from 1 to 31 characters and must conform to the following rules: 


e The first character of an unquoted name must be an alphabetic character (A through Z). 
The remaining characters, if present, can be any combination of letters, digits (0 through 
9), dollar signs ($), periods (.), and underscores (_). 


¢ Quoted names are allowed for the EXTERNAL SUB statement only. Quoted names can 
consist of any combination of printable ASCII characters. 


rely) £~TESNh 


e An EXTERNAL SUB or EXTERNAL FUNCTION statement with empty parentheses speci- 
fies that the named subprogram has zero arguments. 


An EXTERNAL SUB or EXTERNAL FUNCTION statement with no parentheses specifies that 
the named subprogram may receive any number of arguments. 


In BASIC-PLUS—2, the name of an external constant, variable, or subroutine can consist of 
from one to six characters and must conform to the following rules: 


e The first character of an unquoted name must be an alphabetic character (A through Z). 
The remaining characters, if present, can be any combination of letters, digits (0 through 
9), dollar signs ($), and periods (.). 


® Quoted names are allowed for the EXTERNAL SUB statement only. Quoted names can 
consist of any combination of alphabetic characters, digits, dollar signs, periods, and 
spaces. 


External Functions and Subroutines 


1; 


The data-type that precedes the FUNCTION keyword defines the data type of the function 


WG 


Pass-mech specifies how parameters are to be passed to the function or subroutine. 


@ A pass-mech clause outside the parentheses applies to all parameters. 


e A pass-mech clause inside the parentheses overrides the previous pass-mech and applies 
only to the specific parameter. 


External-param defines the form of the arguments passed to the external function or 
subprogram. 


e Empty parentheses indicate that the function or subroutine is being named, but that 
parameters are not being defined. 


e Data-type specifies the data type of a parameter. If you do not specify a data type, 
parameters are of the default data type and size. When you do specify a data type, all 
following parameters are of that data type until you specify a new data type. 
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@ The DIM keyword indicates that the parameter is an array. Commas specify array dimen- 
sions. The number of dimensions is equal to the number of commas plus one. For 
example: 


100 EXTERNAL STRING FUNCTION NEW (DOUBLE+ STRING DIM(+)+ DIM()) 


This example declares a function named NEW that has three parameters. The first is a 
double-precision floating-point value, the second is a two-dimensional string array, and 
the third is a one-dimensional string array. The function returns a string result. 


e You can specify how an argument is to be passed to the function or subprogram with the 
optional pass-mech clause. If you do not specify a passing mechanism for a parameter, 
BASIC passes arguments by the default passing mechanisms listed in Tables 19 and 20. 


General Rules 


168 


1. 


The EXTERNAL statement must precede any program reference to the constant, variable, 
function, or subroutine declared in the statement. 


The EXTERNAL statement is not executable. 


A name declared in an EXTERNAL CONSTANT statement may be used in any nondeclara- 
tive statement as if it were a constant. 


A name declared in an EXTERNAL FUNCTION statement may be used as a function 
invocation in an expression. 


A name declared in an EXTERNAL SUB statement may be used in a CALL statement. 


The optional pass-mech clauses in the EXTERNAL FUNCTION and EXTERNAL SUB 
statements tell BASIC how to pass arguments to a non—BASIC function or subprogram. 
Table 19 describes VAX-17 BASIC parameter passing mechanisms. Table 20 describes 
BASIC—PLUS—2 parameter passing mechanisms. 


e BY REF specifies that BASIC passes the argument’s address. This is the default for all 
arguments except strings and entire arrays. 


e BY VALUE specifies that VAX—11 BASIC passes the argument’s 32-bit value and that 
BASIC—PLUS—2 passes the argument’s 16—bit value. 


e BY DESC specifies that BASIC passes the address of a VAX—11 BASIC descriptor 
or a BASIC—PLUS—2 descriptor. For information about the format of a VAX—11 BASIC 
descriptor for strings and arrays, see Appendix C in BASIC on VAX/VMS Systems. 
BASIC—PLUS—2 creates descriptors only for strings and arrays; these descriptors are de- 
scribed in Appendix C in BASIC on RSX~11M/M-—PLUS Systems and BASIC on RSTS/E 
Systems. 
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rhe passed to external! functions and subroutines should match the external 


argu mes 
sinners pare in the EXTERNAL FUNCTION or EXTERNAL SUB statement in num- 
ber, type, ordinality, and passing mechanism as BASIC forces arguments to conform to the 
declared parameters. BASIC signals an error when conformance is impossible (for exam- 
ple, when a STRING argument is passed where an INTEGER parameter was declared) and 
an informational message when a conversion results in a modifiable parameter becoming a 
nonmodifiable parameter. 


Examples 


External Constants 


100 EXTERNAL LONG CONSTANT SYS#FC 


External Variables 


100 EXTERNAL WORD SYSNUM 


External Functions 


100 EXTERNAL DOUBLE FUNCTION USR$2 (DOUBLE DIM(;>),BYTE BY VALUE) 


External Subroutines 


100 EXTERNAL SUB CALC BY DESC (STRING DIM(;), BYTE BY REF? 
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Function 
Note 


The FIELD statement is supported only for compatibility with BASIC—PLUS. Because 
data defined in the FIELD statement can be accessed only as string data, you must use 
the CVTxx functions to process numeric data. This means that you must convert string 
data to numeric after you move it from the I/O buffer. Then, after processing, you 
must convert numeric data back to string data before transferring it to the |1/O buffer. 
DIGITAL recommends that you use BASIC’s dynamic mapping feature or multiple 
MAPs instead of the FIELD statement and CVTxx functions. 
The FIELD statement dynamically associates string variables with all or parts of an |/O buffer. FIELD 


statements do not move data. Instead, they permit direct access through string variables to sections of 
a specified |/O buffer. 


Format 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be preceded by a pound sign (#). A file must be open on the specified channel or 
BASIC signals an error. 


2. Int-exp specifies the number of characters in the str-vb/ that follows the AS keyword. 


Generai Ruies 
1. A FIELD statement is executable. You can change a buffer description at any time by 
executing another FIELD statement. For example: 


100 FIELD #1%+ 40% AS WHOLE_FIELDS 
FIELD #1%+5 10% AS AS+ 10% AS BS; 10% AS Cs 10% AS DS 


The first FIELD statement associates the first 40 characters of a buffer with the variable 
WHOLE_FIELD$. The second FIELD statement associates the first 10 characters of the 
same buffer with A$, the second 10 characters with B$, and so on. Later program state- 
ments can refer to any of the variables named in the FIELD statements to access specific 
portions of the buffer. 


2. You cannot define virtual array strings as string variables in a FIELD statement. 


3. See the BASIC-PLUS Language Manual for more information on the FIELD statement. 
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VAX-11 BASIC 


1. A-variable named in a FIELD statement cannot be used in a COMMON or MAP statement, 
as a parameter in a CALL or SUB statement, or in a MOVE statement. 


2. Using the FIELD statement on a VIRTUAL file that contains a virtual array causes BASIC to 
signal ‘Illegal or illogical access’ (ERR = 136). 


3. If you name an array in a FIELD statement, you cannot use MAT statements of the format: 
MAT arr-nam1 = arr-nam2 
or 
MAT arr-nam1 = NUL$ 


where arr-nam1 is named in the FIELD statement. An attempt to do so causes BASIC to 
signal a compile-time error. 


Examples 
100 FIELD #8%» 2% AS US+ 2% AS CL,» 4% AS X$+ 4% AS YS 
210 LSET US = CYTZ$(U%) 


LSET CL$ = CYUTZ$(CLA) 
LSET XS = CUTFS(X) 
LSET YS = CUTFS(Y) 


300 UZ = CYT$*ACUS) 
CLA = CVUTSZ(CLS) 
X = CUTSFCXKS) 
Y = CUTSFCYS) 


Note 


DIGITAL does not recommend the FIELD statement for new program development. 
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16.0 FIND 


Function 


The FIND statement locates a specified record in a disk file and makes it the Current Record for a 
GET, UPDATE, or DELETE operation. FIND statements are valid on RMS sequential, relative, in- 
dexed, and block I/O files. You should not use FIND statements on terminal-format files, virtual array 
files, or files opened with ORGANIZATION UNDEFINED. 


Format 


FIND chni-exp [ , position-clause ][ , lock-clause ] 


RFA rfa-exp 
position-clause: RECORD num-exp 
KEY# key-clause 


ALLOW allow-clause 
REGARDLESS 


lock-clause: 


NONE 


allow-clause: READ 
MODIFY 


str-exp 
key-clause: int-exp1 rel-op int-exp2 
decimal-exp 


(continued on next page) 
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BASIC—PLUS—2 
FIND chni-exp [ , position-ciause j 


RFA rfa-exp 
position-clause: RECORD num-exp 
KEY# key-clause 


str-exp 


key-clause: int-exp1 rel-op 


int-exp2 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


2. Position-clause specifies the position of a record in a file. BASIC signals an error if you 
specify a position-clause and chnl-exp is not associated with a disk file. 


e If you do not specify a position-clause, FIND locates records sequentially. Sequential 
record access is valid on RMS sequential, relative, indexed, and block 1/O files. 


@ The RFA position-clause allows you to randomly locate records by specifying the Record 
File Address (RFA) of a record. That is, you specify the disk address of a record, and RMS 
locates the record at that address. All RMS file organizations may be accessed by RFA. 


@ The RECORD position-clause allows you to randomly locate records in relative and 
block I/O files by specifying the record number. 


e The KEY position-clause allows you to randomly locate records in indexed files by speci- 
fying a key of reference, a relational test, and a key value. 


3. Rfa-exp in the RFA position-clause is a variable of the RFA data type that specifies the 
record’s Record File Address. Note that an RFA expression can only be a variable of the 
RFA data type or the GETRFA function. Use the GETRFA function to find the RFA of a 
record. 


4.  Int-exp in the RECORD position-clause specifies the number of the record you want to 
locate. It must be between one and the file’s maximum record number. 
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In the key-clause: 


@ Int-exp1 is the target key of reference. It must be a WORD or LONG integer between 
zero and the highest-numbered key for the file, inclusive. BASIC converts BYTE integers 
to WORD. The primary key is key number zero, the first alternate key is key number 
one, the second alternate key is key number two, and so on. /nt-exp7 must be preceded 
by a pound sign (#) or BASIC signals an error. 


@ Str-exp and int-exp2 specify a string or integer value to be compared with the key value 
of a record. 


¢ Rel-op specifies how str-exp or int-exp2 is to be compared to int-exp?. EQ means ‘‘equal 
to,’’ GE means “greater than or equal to,” and GT means “greater than.” 


When you specify a RECORD clause, chn!-exp must be a channel associated with an open 
relative or block I/O file. 


When you specify a KEY clause, chn/-exp must be a channel associated with an open 
indexed file. 
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Str-exp in the KEY clause cannot be a null string. 


Decimal-exp in the KEY clause specifies a packed decimal value to be compared with the 
key value of a record. 


Lock-clause allows you to control how a record is locked to other access streams. The file 
associated with chnl-exp must have been opened with the UNLOCK EXPLICIT clause or 
BASIC signals the error ‘‘illegal record locking clause’’. 


If you specify a lock-clause, it must follow the position-clause. If the lock-clause precedes 
the position-clause, BASIC signals an error. 


General Rules 


1. 


The file associated with chnl-exp must be opened with ACCESS MODIFY, READ, or 
SCRATCH before your program can execute a FIND. 


FIND does not transfer any data. 


A successful sequential FIND updates both the Current Record and Next Record Pointers. 


e For sequential files, a successful FIND locates the next sequential record (the record 
pointed to by the Next Record Pointer) in the file, changes the Current Record Pointer to 
the record just found, and sets the Next Record Pointer to the next sequential record. If 
the Current Record Pointer points to the last record in a file, a sequential find causes 
BASIC to signal ‘End of file on device” (ERR=11). 


@ For relative files, a successful FIND locates the record with the next higher record num- 


ber (or cell number), makes it the Current Record, and changes the Next Record to the 
Current Record plus one. 
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@ For indexed files, a successful FIND locates the next logical record in the current key of 
reference, makes this the Current Record, and changes the Next Record to the Current 
Record plus one. 


e For block I/O files, a successful FIND locates the next disk block (for files with 
RECORDSIZE 512) or the next record (for files with RECORDSIZE greater than 512), 
makes it the Current Record, and changes the Next Record to the Current Record plus 
one. 


4. A successful random FIND by KEY locates the first record whose key satisfies the 
key-clause comparison: 


® With an exact key match (EQ), a successful FIND locates the first record in the file that 
equals the key value given in int-exp or specified by str-exp. The characters specified by 
str-exp are matched approximately rather than exactly. That is, if you specify “ABC” and 
the key length is six characters, BASIC matches the first record that begins with ABC. If 
you specify ‘‘ABC  ’’, BASIC matches only a record with the key “ABC  ”. If no 
match is possible, BASIC signals the error ‘‘Record not found’ (ERR= 155). 


@ With the greater than key match (GT), a successful FIND locates the first record with a 
value greater than int-exp or str-exp. If no such record exists, BASIC signals the error 
“End of file on device” (ERR=11). 


e If you specify a greater than or equal to key match (GE), a successful FIND locates the 
first record that equals the key value in int-exp or str-exp. If no exact match is possible, 
BASIC locates the first record with a key value higher than int-exp or str-exp. 


5. A successful random access FIND by RFA or by RECORD changes the Current Record 
Pointer to the record specified by rfa-exp or int-exp, but leaves the Next Record Pointer 
unchanged. 


mace es on 


A successful random access FIND by KEY changes the Current Record Pointer to the first 
record whose key satisfies the key-clause comparison and the Next Record Pointer to the 
record with the next higher value in the current key. 


oN 


7. When a random access FIND by RFA, RECORD, or KEY is not successful, BASIC signals 
“Record not found’’ (ERR=155). The values of the Current Record Pointer and Next 
Record Pointer are undefined. 


8. If the RMS index lists are in memory, a FIND on an indexed file does not initiate any disk 
operations. 
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1. The type of lock you impose on a record remains in effect until you explicitly unlock it with 
a FREE or UNLOCK statement or until you close the file. 


e ALLOW NONE specifies no access to the record. This means that other access streams 
cannot retrieve the record unless they bypass lock checking with GET REGARDLESS. 


e ALLOW READ specifies read access to the record. This means that other access streams 
_ can retrieve the record but cannot PUT or UPDATE the record. 


e ALLOW MODIFY specifies both read and write access to the record. This means that 
other access streams can GET, PUT, DELETE, or UPDATE the record. 
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2. When you do not specify an ALLOW clause, locking is imposed as follows: 


e |f the file associated with chnl-exp was opened with UNLOCK EXPLICIT, BASIC imposes 
the ALLOW NONE lock on the retrieved record and the next GET or FIND does not 
unlock the previously locked record. 


e If the file associated with chnl-exp was not opened with UNLOCK EXPLICIT, BASIC locks 
the retrieved record and unlocks the previously locked record. 


BASIC—PLUS—2 


1. When you access a shared file, a successful FIND locks the record or bucket and unlocks 
the previously iocked record or bucket. 


Examples 


Sequential Access 


100 MAP (XYZ) STRING LAST_NAME = 10+ FIRST_NAME = 6 
150 OPEN ‘EMP.DAT’ AS FILE #1, & 
ORGANIZATION SEQUENTIAL,» MAP XYZ 
200 FIND #1 
Random Access 
100 DECLARE RFA Address(99) 
200 MAP (XYZ) STRING LAST_NAME = 10, FIRST_NAME = 6&6 
300 OPEN ‘EMP.DAT’ AS FILE #1; & 


ORGANIZATION SEQUENTIAL: MAP KY2Z 
400 FIND #1 
Address(0) = GETRFA(1) 
{ 
! 
i 


300 FIND #1+ RFA Address(5) 

! 

! 

! 
600 OPEN ‘NEWEMP.DAT’ AS FILE #2, & 

ORGANIZATION RELATIVE+s MAP KY2 

700 FIND #2, RECORD AZ 

Address(AZ) = GETRFA(2) 


! 
I 
! 
FIND #2+ RFA Address(AZ) 
! 
! 
I 


900 OPEN ‘OLDEMP.DAT’ AS FILE #3; & 

ORGANIZATION INDEXED: MAP KY¥Z;s & 
PRIMARY KEY LAST_NAME 

FIND #3; KEY #0 EQ "JONES" 

Address(S) = GETRFAC3) 

| 

| 

! 

FIND #3; RFA Address(7) 
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BASIC 


MAP (X¥Z) STRING LAST_NAME = 10; FIRST_NAME = G&G 
OPEN ’EMP.DAT’ AS FILE #1; 

ORGANIZATION INDEXED: 

MAP X¥2Z+ PRIMARY KEY LAST_NAME + 

UNLOCK EXPLICIT 
FIND #3, KEY #0 EQ "JONES"+ ALLOW READ 
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Function 
The FNEND statement is a synonym for END DEF. See the END statement for syntax rules. 


Format 
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18.0 FNEXIT 


Function 


The FNEXIT statement is a synonym for the EXIT DEF statement. See the EXIT statement for syntax 
rules. 


Format 


FNEXIT 


EXIT DEF 
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19.0 FOR 
Function 


The FOR statement repeatedly executes a block of statements, while incrementing a specified control 
variable for each execution of the statement block. FOR loops can be conditional or unconditional, 
and can modify other statements. 


Format 


Unconditional 
FOR num-unsubs-vb! = num-exp1 TO num-exp2 [ STEP num-exp3 ] 


[ statement ]... 


Conditional 


UNTIL 
WHILE 


FOR num-unsubs-vbI = num-exp1 [ STEP num-exp3 ] cond-exp 
{ statement ]... 
NEXT num-unsubs-vb! 
Unconditional Statement Modifier 
statement FOR num-unsubs-vbl = num-exp1 TO num-exp2 [ STEP num-exp3 ] 


Conditional Statement Modifier 


UNTIL 
WHILE 


NEXT num-unsubs-vbl 


statement FOR num-unsubs-vbl = num-exp1 [ step num-exp3 ] 


cond-exp 


Syntax Rules 
1. Num-unsubs-vbl is the loop variable. It is incremented each time the loop executes. 


2. In unconditional FOR loops, num-exp1 is the initial value of the loop variable, while 
num-exp2 is the maximum value. 


3. In conditional FOR loops, num-exp7 is the initial value of the loop variable, while the 
cond-exp in the WHILE or UNTIL clause is the condition that controls loop iteration. 


4. Num-exp3 in the STEP clause is the value by which the loop variable is incremented after 
each execution of the loop. 


5. In VAX-11 BASIC, you can nest FOR loops to a maximum of 12 levels, depending on the 
complexity of the loops. 
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In BASIC—PLUS—2, you nest FOR loops to a maximum of 8 levels, depending on the 
complexity of the loops. 


ied etoed 
An inner loop must be entirely within an outer loop; the loops cannot overlap. 


You cannot use the same loop variable in nested FOR loops. That is, if the outer loop uses 
“FOR | = 1 TO 10”, you cannot use the variable | as a loop variable in an inner loop. 


The default for num-exp3 is one if there is no STEP clause. 


You can transfer control into a FOR loop only be returning from a function invocation, a 
subprogram call, or an error handler that was invoked in the loop. 


Each FOR statement must have a corresponding NEXT statement or BASIC signals and 
error. 


General Rules 


1. 


The starting, incrementing, and ending values of the loop do not change during loop 
execution. 


BASIC converts num-exp1, num-exp2, and num-exp3 to the data type of num-unsubs-vbl 
When an unconditional FOR loop ends, the loop variable contains the value last used in 


During each iteration of a conditional loop, BASIC tests the value of cond-exp before it 


e If you specify a WHILE clause and cond-exp is false (value zero), BASIC exits from the 
loop. If the cond-exp is true (value nonzero), the loop executes again. 


e if you specify an UNTIL clause and cond-exp is true (value nonzero), BASIC exits from 
the loop. If the exp is false (value zero), the loop executes again. 


When FOR is used as a statement modifier, BASIC executes the statement until 
num-unsubs-vbl equals or exceeds num-exp2 or until the WHILE or UNLESS condition is | 


2. The loop variable can be modified inside the FOR loop. 
3: 
(the loop variable) before storing them. 
4. 
the loop, not the value that caused loop termination. 
5. 
executes the loop. 
6. 
satisfied. 
Examples 


Unconditional 


350 FOR I = 3 TO 99 STEP 3 
y 
| 
! 

400 NEAT I 


Unconditional 

100 FOR Z = 0 STEP 2? UNTIL X 
i 
| 
| 

200 NEXT Z 
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Unconditional Statement Modifier 


100 A = A + .0005 FOR I = i TO 10 


Conditional Statement Modifier 


100 FIND #2 FOR I = i UNTIL ERR=155 
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20.0 FREE (VAX-—11 BASIC) 


Function 


The FREE statement unlocks all records and buckets associated with a specified channel. 


Format 


FREE chni-exp 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


General Rules 
1. The file specified by chni-exp must be open. 
2. You cannot use the FREE statement with files not on disk. 


3. If there are no locked records or buckets on the specified channel, the FREE statement has 
no effect and BASIC does not signal an error. 


4. The FREE statement does not change record buffers or pointers. 


5. Your program must execute a GET or FIND statement after a FREE statement executes 
before a PUT statement can execute. 


Examples 


450 FREE #6% 
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21.0 FUNCTION 
Function 


The FUNCTION statement marks the beginning of a FUNCTION subprogram and defines the subpro- 
gram’s parameters. 


Format 
VAX-11 BASIC 
FUNCTION data-type func-nam [ pass-mech ] [ ( [ formal-param ],... ) ] 
[ statement ]... 


END FUNCTION | 
( FUNCTIONEND } 


pass-mech: | BY REF 


{ BY DESC 


formal-param: unsubs-vbl-nam 
[ data-type ] @ array-nam ( aia . ) } [ = int-const ] [ pass-mech ] 


BASIC-—PLUS-2 ay, 
FUNCTION data-type func-nam [ ( [ formal-param ],... ) ] 
[ statement ]... 


END FUNCTION 
FUNCTIONEND 


formal-param: unsubs-vbl-nam 
[ data-type ] 2 array-nam ( baal ee) 
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Te 


Func-nam names the FUNCTION subprogram. The last character of the name cannot be a 
dollar sign ($). 


Data-type can be any BASIC data-type keyword or, in VAX—11 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manual. 


The data-type that precedes the func-nam specifies the data type of the value returned by 
the FUNCTION subprogram. 


Formal-param specifies the number and type of parameters for the arguments the 
FUNCTION subprogram expects to receive when invoked. 


e Empty parentheses indicate that the FUNCTION subprogram has zero parameters. 


e Data-type specifies the data type of a parameter. If you do not specify a data type, 
parameters are of the default data type and size. When you do specify a data type, all 
following parameters are of that data type until you specify a new data type. 


e If you specify a data-type, unsubs-vbl-nam and array-nam cannot end in a percent sign 
(%) or dollar sign ($). 


e Parameters defined in formal-param must agree in number and type with the arguments 
specified in the function invocation. 


The FUNCTION statement must be the first statement in the FUNCTION subprogram. 


Compiler directives and comment fields (!), because they are not BASIC statements, may 
precede the FUNCTION statement. However, they cannot precede the subprogram’s first 
numbered line. Note that REM is a BASIC statement; therefore, it cannot precede the 
FUNCTION statement. 


Every FUNCTION statement must have a corresponding END FUNCTION statement or 
FUNCTIONEND statement. 


Any BASIC statement except END, SUB, SUBEND, END SUB, or SUBEXIT can appear in a 
FUNCTION subprogram. 
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1. 


Func-nam can consist of from 1 to 31 characters The first character must be an alphabetic 
character (A through Z). The remaining characters, if present, can be any combination of 
letters, digits (0 through 9), dollar signs ($), periods (.), or underscores (_). 


If the data type is STRING, the =int-const clause allows you to specify the length of the 
string. The default string length is 16. 


VAX—11 BASIC allows you to specify from 1 to 32 formal-params. 
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4. Pass-mech specifies the parameter passing mechanism by which the FUNCTION sub- 
program receives arguments when invoked. A pass-mech should be specified only when 
the FUNCTION subprogram is being called by a non—BASIC program. 


5. A pass-mech clause outside the parentheses applies by default to all FUNCTION parame- 
ters. A pass-mech clause in the formal-param list overrides the specified default and applies 
only to the immediately preceding parameter. 


BASIC—PLUS—2 


1. Func-nam can consist of from one to six characters. The first character must be an alpha- 
betic character (A through Z). The remaining characters, if present, can be any combina- 
tion of letters, digits (0 through 9), dollar signs ($), and periods (.). 


2. BASIC—PLUS-—2 allows you to specify from one to eight formal-params. 


General Ruies 


1. FUNCTION subprograms must be declared with the EXTERNAL statement before your 
program can invoke them. 


2. FUNCTION subprograms receive parameters BY REF or BY DESC. 
e BY REF specifies that the FUNCTION subprogram receives the argument’s address. 


e BY DESC specifies that the FUNCTION subprogram receives the address of a VAX—11 
BASIC descriptor or a BASIC—PLUS—2 descriptor. For information about the format of a 
VAX—11 BASIC descriptor for strings arid arrays, see Appendix C in BASIC on VAX/VMS 
Systems; for information on other types of descriptors, refer to the VAX Architecture 
Handbook. BASIC—PLUS—2 creates descriptors only for strings and arrays; these descrip- 
tors are described in Appendix C in BASIC on RSX—11M/M-—PLUS Systems and BASIC on 
RSTS/E Systems. 


3. All variables and data, except virtual arrays, COMMON areas, and MAP areas in a 
FUNCTION subprogram, are local to the subprogram. 


4. BASIC initializes local numeric variables to zero and local string variables to the null string 
each time the FUNCTION subprogram is invoked. 


5. ON ERROR GO BACK is the default error handler for a FUNCTION subprogram. 


BASIC—PLUS—2 


1. BASIC—-PLUS—2 receives numeric unsubs-vbls BY REF and string unsubs-vbls and entire 
arrays BY DESC. 


VAX-11 BASIC 


1. By default, VAX—17 BASIC FUNCTION subprograms receive numeric unsubs-vbls BY REF, 
and all other parameters BY DESC. You can override these defaults with a BY clause: 


e Any parameter can be received BY DESC. 
° To receive a string parameter BY REF, you must specify the string length. 


e To receive an entire array BY REF, you must specify the array bounds. 
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Examples 
VAX—11 BASIC only 


100 FUNCTION GFLOAT SIGMA BY DESC & 
(GFLOAT A(20+20) » &. 
B+ HFLOAT C BY REF) 
i 
| 
i 


250 END FUNCTION 


BASIC—PLUS—2 only 


100 FUNCTION DOUBLE CALC (SINGLE A» B+» DOUBLE C(10;+50)) 
1 
! 
! 

250 END FUNCTION 
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22.0 FUNCTIONEND 
Function 


The FUNCTIONEND statement is a synonym for the END FUNCTION statement. See the END 
statement for syntax rules. 


Format 


| FUNCTIONEND | 


| ( END FUNCTION | | 
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23.0 FUNCTIONEXIT 


Function 


The FUNCTIONEXIT statement is a synonym for the EXIT FUNCTION statement. See the EXIT state- 
ment for syntax rules. 


Format 


FUNCTIONEXIT 


EXIT FUNCTION 
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24.0 GET 


Function 


The GET statement moves a record from a file to a record buffer and makes the data available for 
processing. GET statements are valid on RMS sequential, relative, indexed, and block I/O files, and 
on RSTS/E non—RMS block |/O files. You should not use GET statements on terminal-format files, 
virtual array files, or files opened with ORGANIZATION UNDEFINED. 


Format 
VAX-11 BASIC 
GET chnl-exp [ , position-clause | [ , lock-clause ] 


RFA rfa-exp 
RECORD num-exp 
KEY# key-clause 


position-clause: 


ALLOW allow-clause 
| REGARDLESS 


lock-clause: 


NONE 
allow-clause: READ 
MODIFY 


str-exp 
key-clause: int-exp1 rel-op int-exp2 
decimal-exp 


(continued on next page) 
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BASIC-—PLUS-2 


GET chnl-exp [ , position-clause ] 


RFA rfa-exp 
position-clause: RECORD num-exp 
KEY# key-clause 


key-clause: int-exp1 rel-op | St-exP 
int-exp2 
EQ 
rel-op: GE 
GT 


Syntax Rules 
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Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


Position-clause specifies the position of a record in a file. BASIC signals an error if you 
specify a position-clause and chnl-exp is not associated with a disk file. 


e If you do not specify a position-clause, GET retrieves records sequentially. Sequential 
record access is valid on RMS sequential, relative, indexed, and block |/O files. 


e The RFA position-clause allows you to randomly retrieve records by specifying the Rec- 
ord File Address (RFA) of a record. That is, you specify the disk address of a record, and 
RMS retrieves the record at that address. All RMS file organizations may be accessed by 
RFA. 


e The RECORD position-clause allows you to randomly retrieve records in relative and 
block |/O files by specifying the record number. 


e The KEY position-clause allows you to randomly retrieve records in indexed files by 
specifying a key of reference, a relational test, and a key value. 


Rfa-exp. in the RFA position-clause is an expression of the RFA data type that specifies the 
record’s Record File Address. Note that an RFA expression can be only a variable of the 
RFA data type or the GETRFA function. Use the GETRFA function to find the RFA of a 
record. 


Int-exp in the RECORD position-clause specifies the number of the record you want to 
retrieve. It must be between one and the file’s maximum record number. 
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In the key-clause: 


e Int-exp1 is the target key of reference. It must be a WORD or LONG integer between 
zero and the highest-numbered key for the file, inclusive. BASIC converts BYTE integers 
to WORD. The primary key is key number zero, the first alternate key is key number one, 
the second alternate key is key number two, and so on. Int-exp7 must be preceded by a 
pound sign (#) or BASIC signals an error. 


e Str-exp and int-exp2 specify a string or integer value to be compared with the key value of 
a record. Str-exp can contain fewer characters than the key of the record you want to 
retrieve. 


e Rel-op specifies how str-exp or int-exp2 is to be compared to int-exp71. EQ means “‘equal 
to,’” GE means “greater than or equal to,”” and GT means “greater than.” 


When you specify a RECORD clause, chn/-exp must be a channel associated with an open 
relative or block I/O file. 


When you specify a KEY clause, chni-exp must be a channel associated with an open 
indexed file. 
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1. 
2. 


Str-exp in the KEY clause cannot be a null string. 


Decimal-exp in the KEY clause specifies a packed decimal value to be compared with the 
key value of a record. 


Lock-clause allows you to control how a record is locked to other access streams or to 
override lock checking when accessing shared files that may contain locked records. 


If you specify a lock-clause, it must follow the position-clause. If the lock-clause precedes 
the position-clause, BASIC signals an error. 


If you specify an allow-clause, the file associated with chnl-exp must have been opened 
with the UNLOCK EXPLICIT clause or BASIC signals the error ‘‘illegal record locking 
clause’’. 


General Rules 


1. 


The file specified by chnl-exp must be open with ACCESS READ or MODIFY before your 
program can execute a GET. The default ACCESS clause is MODIFY. 


If the last |/O operation was a successful FIND, a sequential GET retrieves the Current 
Record located by the FIND and sets the Next Record Pointer to the Current Record plus 
one. 


If the last |/O operation was not a FIND, a sequential GET retrieves the Next Record and 
sets the Next Record Pointer to the Current Record plus one. 


e For sequential files, a sequential GET retrieves the next record in the file. 


e For relative and block I/O files, a sequential GET retrieves the record with the next 
higher cell number. 


e For indexed files, a sequential GET retrieves the record with the next higher value in the 
current key of reference. 
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10. 


11. 


A successful random GET by RFA or by RECORD retrieves the record specified by rfa-exp 
or int-exp. 


A successful random GET by KEY retrieves the first record whose key satisfies the 
key-clause comparison: 


e With an exact key match (EQ), a successful GET retrieves the first record in the file that 
equals the key value given in int-exp or specified by str-exp. The characters specified by 
str-exp are matched approximately rather than exactly. That is, if you specify ““ABC’’ and 
the key length is six characters, BASIC matches the first record that begins with ABC. If 
you specify “ABC ’’, BASIC matches only a record with the key “ABC ”. If no 
match is possible, BASIC signals the error ‘‘Record not found’ (ERR= 155). 


e With the greater than key match (GT), a successful GET retrieves the first record with a 
value greater than int-exp or str-exp. If no such record exists, BASIC signals the error ‘End 
of file on device’ (ERR= 11). 


e If you specify a greater than or equal to key match (GE), a successful GET retrieves the 
first record that equals the key value in int-exp or str-exp. If no exact match is possible, 
BASIC retrieves the first record with a key value higher than int-exp or str-exp. 


A successful random GET by RFA, RECORD, or KEY sets the value of the Current Record 
Pointer to the record just read. The Next Record Pointer is set to the Current Record plus 
one. 


An unsuccessful GET leaves the record pointers and the !/O buffer in an undefined state. 


If the retrieved record is smaller than the receiving buffer, BASIC fills the remaining buffer 
space with nulls. 


If the retrieved record is larger than the receiving buffer, BASIC truncates the record and 


signals an error. 


A successful GET sets the value of the RECOUNT variable to the number of bytes trans- 
ferred from the file to the record buffer. 


Because a GET statement on a block I/O file always transfers an integral number of 
512—byte disk blocks, your program must perform record blocking and deblocking. See 
Chapter 9 in the BASIC User’s Guide for more information. 
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The type of lock you impose on a record remains in effect until you explicitly unlock it with 
a FREE or UNLOCK statement or until you close the file. 


e ALLOW NONE specifies no access to the record. This means that other access streams 
cannot retrieve the record unless they bypass lock checking with GET REGARDLESS. 


e ALLOW READ specifies read access to the record. This means that other access streams 
can retrieve the record, but cannot PUT or UPDATE the record. 


e ALLOW MODIFY specifies both read and write access to the record. This means that 
other access streams can GET, PUT, DELETE, or UPDATE the record. 
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2. When you do not specify an ALLOW clause, locking is imposed as follows: 


e If the file associated with chn/-exp was opened with UNLOCK EXPLICIT, BASIC imposes 
the ALLOW NONE lock on the retrieved record and the next GET or FIND does not 
unlock the previously locked record. 


e If the file associated with chn/-exp was not opened with UNLOCK EXPLICIT, BASIC locks 
the retrieved record and unlocks the previously locked record. 


3. REGARDLESS specifies that the GET statement can override lock checking and read a 
record locked by another program. 


4. REGARDLESS does not impose a lock on the retrieved record. 


BASIC—PLUS—2 
1. When you access a shared file, a successful GET locks the record or bucket and unlocks 
the previously locked record or bucket. 


Examples 


Sequential Access 


100 MAP (X¥Z) STRING LAST_NAME = 10; FIRST_NAME = & 
150 OPEN ‘’EMP.DAT’ AS FILE #1, & 

ORGANIZATION SEQUENTIAL» MAP KY2 
200 GET #4 


Random Access 


100 MAP (XYZ) STRING LAST_NAME = 10+ FIRST_NAME = 6 
200 DECLARE RFA Address(99) 
366 OPEN ‘EMP.DAT’ AS FILE #1» & 


ORGANIZATION SEQUENTIALs MAP XYZ 
466 GET #1 
Address(0) = GETRFA(1) 
{ 


300 GET #1+ RFA Address(35) 
! 
! 
! 
600 OPEN ‘’NEWEMP.DAT’ AS FILE #2; & 
ORGANIZATION RELATIVE+s MAP KYZ 
700 GET #2+ RECORD AZ 


Address(AZ) = GETRFA(2) 
! 


| 
! 
FIND #2+ RFA Address(AX%) 
! 


! 
! (continued on next page) 
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900 OPEN ‘OLDEMP.DAT’ AS FILE #3, 


ORGANIZATION INDEXED:+ MAP XYZ+ 
PRIMARY KEY LAST_NAME 
GET #3,» KEY #0 EQ "JONES" 


Address(5) = GETRFA(3) 
! 


GET #3, RFA Address(7) 
VAX—11 BASIC 


100 MAP (XYZ) STRING LAST_NAME = 10; 
300 OPEN ’EMP.DAT’ AS FILE #1; 
ORGANIZATION INDEXED: 


MAP XYZ> PRIMARY KEY LAST NAME + 
UNLOCK EXPLICIT 


GET #1, KEY #0 EQ "JONES"+ ALLOW READ 


FIRST NAME 


400 
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GOSUB 


Function 


The GOSUB statement transfers control to a specified line number or label and stores the location of 
the GOSUB statement for eventual return from the subroutine. 


Format 


GOSUB target 


Syntax Rules 


1. Target must refer to an existing line number or label in the same program unit as the 
GOSUB statement or BASIC signals an error. 


2. Target cannot be inside a FOR/NEXT, WHILE, or UNTIL loop or a multi-line function 
definition unless the GOSUB statement is also within that loop or function definition. 


General Rules 


None. 
Examples 


200 GOSUB 1100 


1100 Subroutine 1 


! 
I 
4 
! 
! 
! 
! 
R 


2100 ETURN 
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GOTO 


26.0 GOTO 


Function 


The GOTO statement transfers control to a specified line number or label. 


Format 


GO TO 


GOTO | target 


Syntax Rules 


1. Target must refer to an existing line number or label in the same program unit as the GOTO 
statement or BASIC signals an error. 


2. Target cannot be inside a FOR/NEXT, WHILE, or UNTIL loop or a multi-line function 
definition unless the GOTO statement is also inside that loop or function definition. 


General Rules 


None. 
Examples | 


20 GOTO 200 
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IF 


Function 


The IF statement evaluates a conditional expression and transfers program control depending on the 
resulting value. 


Format 


| Conditional | 


statement... 
THEN lin-num lin-num 
ELSE statement... {f END IF ] 


IF cond-exp 
GOTO target 


Statement Modifier 


statement IF cond-exp 


Syntax Rules 
Conditional 
1. Cond-exp can be any valid conditional expression. 


2. Any executable statement is valid in the THEN or ELSE clause, including another IF state- 
meni. You can inciude any number of siatemenis in either ciause. 


3. All statements between the keyword THEN and the next ELSE, line number, or END iF are 
part of the THEN clause. All statements between the ELSE keyword and the next line 
number or END IF are part of the ELSE clause. 


4. You can omit the THEN keyword when the target of a GOTO statement in the THEN is a 
lin-num. The THEN keyword is required when the target of a GOTO statement is a label. 


5. BASIC assumes a GOTO statement when the ELSE keyword is followed by a lin-num. 
When the target of a GOTO statement is a label, the GOTO keyword is required. 


6. If a THEN or ELSE clause contains a FOR, SELECT, UNTIL, or WHILE statement, then a 
corresponding NEXT or END statement must appear in the same THEN or ELSE clause. 


7. IF statements can be nested to 12 levels. 
8. The END IF statement terminates the most recent unterminated IF statement. 


9. A new line number terminates all unterminated IF statements. 
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IF 


Statement Modifier 


can "hep Mn AARP iba b lA ats 
1. IF can modify any executable sta 


UNTIL, or SELECT. 
2. Cond-exp can be any valid conditional expression. 
General Rules 
Conditional 


1. BASIC evaluates cond-exp for truth or falsity. If true (nonzero), BASIC executes the THEN 
clause. If false (zero), BASIC skips the THEN clause and executes the ELSE clause, if 
present. 


2. The NEXT keyword cannot be in a THEN or ELSE clause unless the IF statement associated 
with the NEXT keyword is also part of the THEN or ELSE clause. 


3. Execution continues at the statement following the END IF or ELSE clause. If the statement 
does not contain an ELSE clause, execution continues at the next statement after the THEN 
clause. 


Statement Modifier 
1. BASIC executes statement only if the cond-exp is true (nonzero). 
Exampies 


Conditional 


19000 IF ERR = il 


THEN 
IF ERL = 1000 
THEN GOTO ERROR_ROUTINE 
ELSE 
IF ERL = 2000 
THEN 32700 
ELSE 
IF ERL = 3000 
THEN GOTO ERROR ROUTINE 
END IF 
END IF 
END IF 
ELSE PRINT ERT$(ERR) 
END IF 
Statement Modifier 
100 PRINT ‘END OF PROCESSING’ IF ERR = 11 
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INPUT 


28.0 INPUT 


Function 


The INPUT statement assigns values from your terminal or from a terminal-format file to program 
variables. 


Format 


| INPUT [ chnl-exp, ] [ prompt ] vbi [ sep [ prompt ] vbl ]... | 


prompt: sir-const sep 


Syntax Rules 


1. Chnil-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


2. VbI cannot be a DEF function name unless the INPUT statement is inside the multi-line DEF 
that defines the function. 


General Rules 
1. The default chni-exp is zero (the controlling terminal). If a chnl-exp is specified, a file must 
be open on that channel with ACCESS READ or MODIFY before the INPUT statement can 
execute. 
2. You can include more than one prompt in an INPUT statement. The first prompt is issued 
for the first vbI, the second prompt for the second vb!, and so on. The sep that follows the 


vb! associated with the prompt has no formatting effect. BASIC always advances to a new 
line when you terminate input with a carriage return. 


3. Sep in the prompt clause determines where the question mark is displayed and where the 
cursor is positioned for input. 


e A comma tells BASIC to skip to the next print zone and display the question mark. For 
example: 


100 INPUT ‘NAME’ »sYOUR_NAMES 
Run 


NAME ? 
e A semicolon tells BASIC to display the question mark next to str-const. For example: 


100 INPUT ‘ADDRESS’ sADDRS 
Run 


ADDRESS? 
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INPUT 


4. BASIC signals an error if the INPUT statement has no argument. 


5. If input comes from a terminal, BASIC displays the contents of str-const, if present, and a 
question mark (2). If you have not specified a str-const, BASIC displays only the question 
mark. The program then waits for data. 


6. If the open channel does not correspond to a terminal, BASIC displays only the question 
mark. 


7. When BASIC receives a line terminator or a complete record, it checks each data element 
for correct data type and range limits, then assigns the values to the corresponding 
variables. 


8. If you specify a string variable to receive the input text, and the user enters an unquoted 
string in response to the prompt, BASIC ignores the string’s leading and trailing spaces and 
tabs. An unquoted string cannot contain any commas. 


9. When you enter several data elements in response to the INPUT prompt, you must separate 
them with commas. 


10. If there is not enough data in the current record or line to satisfy the variable list, BASIC 
takes one of the following actions: 


e If the input device is a terminal, BASIC repeats the question mark, but not the str-const, 
on a new line until sufficient data is entered. 


e lf the input device is not a terminal, BASIC signals ‘‘Not enough data in record” 
(ERR= 59). 


11. If there are more data items than variables in the INPUT response, BASIC ignores the 
excess. 


12. If there is an error in converting or assigning data (for example, assigning string data to a 
numeric variable), BASIC takes one of the following actions: 


@ If the input device is a terminal, BASIC signals a warning, reexecutes the INPUT state- 
ment, and displays str-const and the question mark. 


e If the input device is not a terminal, BASIC signals ‘Illegal number’’ (ERR = 52) or ‘Data 
format error’ (ERR =50). 


13. When a RESUME statement transfers control to an INPUT statement, the INPUT statement 
retrieves a new record regardless of any data left in the previous record. 


14. After a successful INPUT statement, the RECOUNT variable contains the number of char- 
acters transferred from the file or terminal to the record buffer. 
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15, 


INPUT 


If you terminate input text with CTRL/Z, BASIC assigns the value to the variable and signals 
“End of file on device’ (ERR= 11) when the next terminal input statement executes. If there 
is no next INPUT, INPUT LINE, or LINPUT statement in the program, the CTRL/Z is passed 
to BASIC as a signal to exit the BASIC environment. BASIC signals ‘‘Unsaved changes have 
been made, CTRL/Z or EXIT to exit’ if you have made changes to your program. If you 
have not made changes, BASIC exits from the BASIC environment and does not signal an 
error. 


INPUT "TYPE IN 3 INTEGE 


Bourtay 
: ww awe oy ue 


* ay 
7rtas 7 Lf As 


2 my 
? Lar Aa 


INPUT #3%+, RECORD_STRINGS 


INPUT #124 "PURCHASE NUMBER" SPO_NUMZ3 "“COST"$ COSTs "ID NUMBER"SID4Z 
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29.0 INPUT LINE 


Function 


The INPUT LINE statement assigns a string value, including the line terminator, from a terminal or 
terminal-format file to a string variable. 


Format 


INPUT LINE [ chnl-exp, ] [ prompt ] str-vbl [ sep [ prompt ] str-vbl ]... 


prompt: str-const sep 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


2. VbI cannot be a DEF function name unless the INPUT LINE statement is inside the multi- 
line DEF that defines the function. 


General Rules 


1. The default chnl-exp is zero (the controlling terminal). If a chn/-exp is specified, a file must 
be open on that channel with ACCESS READ before the INPUT LINE statement can exe- 
cute. 


2. You can include more than one prompt in an INPUT LINE statement. The first prompt is 
issued for the first vbl, the second prompt for the second vbi, and so on. The sep that 
follows the vb/ associated with the prompt has no formatting effect. BASIC always 
advances to a new line when you terminate input with a carriage return. 


3. Sep in the prompt clause determines where the question mark is displayed and where the 
cursor is positioned for input. 


e A comma tells BASIC to skip to the next print zone and display the question mark. For 
example: 


100 INPUT LINE ‘NAME’ +YOUR NAME 
Run 


NAME ? 
e A semicolon tells BASIC to display the question mark next to str-const. For example: 


100 INPUT LINE ‘ADDRESS’ sADDRS 
Run 


ADDRESS? 
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10. 


Examples 


650 


390 


INPUT LINE 


If input comes from a terminal, BASIC displays the contents of str-const, if present, and a 
question mark (2). If you have not specified a str-const, BASIC displays only the question 
mark. The program then waits for data. 


If chnl-exp does not correspond to a terminal, BASIC displays only the question mark. 


The INPUT LINE statement assigns all input characters including the line terminator(s) to 
str-vbl. Single and double quotation marks, commas, tabs, leading and trailing spaces, or 
other special characters in the string are part of the data. 


When a RESUME statement transfers control to an INPUT LINE statement, the INPUT LINE 
statement retrieves a new record regardless of any data left in the previous record. 


After a successful INPUT LINE statement, the RECOUNT variable contains the number of 
characters transferred from the file or termina! to the record buffer. 


If you terminate input text with CTRL/Z, BASIC assigns the value to the variable and signals 
“End of file on device’ (ERR = 11) when the next terminal input statement executes. If there 
is no next INPUT, INPUT LINE, or LINPUT statement in the program, the CTRL/Z is passed 
to BASIC as a signal to exit the BASIC environment. BASIC signals ‘“Unsaved changes have 
been made, CTRL/Z or EXIT to exit’ if you have made changes to your program. If you 
have not made changes, BASIC exits from the BASIC environment and does not signal an 
error. 


INPUT LINE "Type two words"+ Z2$+"Type your name" SNS 


INPUT LINE #4%+ RECORD_STRINGS 
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ITERATE 


30.0 ITERATE 


Function 


The ITERATE statement allows you to explicitly reexecute a loop. 


Format 


ITERATE [ label ] 


Syntax Rules 
1. Label is the label of the first statement of a FOR—NEXT, WHILE, or UNTIL loop 
2. The ITERATE statement can be used only within a FOR-NEXT, WHILE, or UNTIL loop. 


General Rules 


1. ITERATE is equivalent to an unconditional branch to the current loop’s NEXT statement. If 
you supply a label, ITERATE transfers control to the NEXT statement in the specified loop. If 
you do not supply a /abel, ITERATE transfers control to the current loop’s NEXT statement. 


2. Label must conform to the rules for naming variables. 
Examples 


1000 Date_loop: WHILE 1% = 1i% 
GET #1 
ITERATE Date wlooe IF Day$ <> Todays 
ITERATE Date_loorp IF Month <> This_month$s 
ITERATE Date_loop IF Year <> This_vear$ 
PRINT Items 
NEXT 
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KILL 


31.0 KILL 


Function 


The KILL statement deletes a disk file, removes the file’s directory entry, and releases the file’s storage 
space. 


Format 


| KILL file-spec . | 


Ee ee a en 


Syntax Rules 


1. File-spec can be a quoted string constant, a string variable, or a string expression. It cannot 
be an unquoted string constant. 


General Rules 


1. The KILL statement marks a file for deletion but does not delete the file until! all users have 
closed it. 


2. If you do not specify a complete file-spec, BASIC uses the default device and direc- 
tory. If you do not specify a file version, VAX-11 BASIC and BASIC—PLUS-—2 on 
RSX~11M/M-—PLUS systems delete the highest version of the file. 


3. The file-spec must exist or BASIC signals an error. 


4. You can delete a file in another directory if you have access to that directory and privilege 
to delete the file. 


Examples 


200 KILL "TEMP.DAT" 
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LET 


32.0 LET 


Function 


The LET statement assigns a value to one or more variables. 


Format 


[LET] vbl,... = exp 


Syntax Rules 


1. 


De 
a 


VbI cannot be a DEF or FUNCTION name unless the LET statement occurs inside that DEF 
block or in that FUNCTION subprogram. 


You cannot assign string data to a numeric variable or numeric data to a string variable. 


The keyword LET is optional. 


General Rules 


1. 


Examples 


10 
20 


206 


When you assign a value to a subscripted variable, BASIC evaluates the subscripts from left 
to right before evaluating exp and assigning the value. In the following example, line 10 
assigns the value 5 to I, then line 20 assigns the value 2 to A(5) and to |: 


10 LET I = 5 
20 LET ACI)sI = 2 


The vaiue assigned to a numeric variabie is converted to the variable’s data type. For 
example, if you assign a floating-point value to an integer variable, BASIC truncates the 
value to an integer. 


For dynamic strings, the destination string’s length equals the source string’s length. 


When you assign a value to a fixed-length string variable, the value is left-justified and 
padded with spaces or truncated to match the length of the string variable. 


LET A = 3.141 
A$ = "ABCDEFG" 
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33.0 LINPUT 


Function 


The LINPUT statement assigns a string value, without line terminators, from a terminal or terminal- 
format file to a string variable. 


Format 


| LINPUT [ chni-exp, ] [ prompt ] str-vbl [ sep [ prompt ] str-vbl ]... | 


prompt: str-const sep 


Syntax Rules 


1. Chnil-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


2. VbI cannot be a DEF function name unless the LINPUT statement is inside the multi-line 
DEF that defines the function. 


General Rules 


It 


-exp iS zero (the controlling terminal). tf you specify a chni-exp, the file 
seeotiaied with that channel must have been opened with ACCESS READ or MODIFY. 


u chnhi-e 
tai 


2. You can include more than one prompt in an INPUT LINE statement. The first prompt is 
issued for the first vb/, the second prompt for the second vb/, and so on. The sep that 
follows the vb/ associated with the prompt has no formatting effect. BASIC always 
advances to a new line when you terminate input with a carriage return. 


3. Sep in the prompt clause determines where the question mark is displayed and where the 
cursor is positioned for input. 


e A comma tells BASIC to skip to the next print zone and display the question mark. For 


example: 

100 LINPUT "NAME" +YOUR_NAME 

Run 

NAME ? (continued on next page) 
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LINPUT 


10. 


Examples 
100 


200 


e A semicolon tells BASIC to display the question mark next to str-const. For example: 


100 LINPUT "ADDRESS" ;A€DDRS 
Run 


ADDRESS? 


BASIC signals an error if the LINPUT statement has no argument. 


If input comes from a terminal, BASIC displays the contents of str-const, if present, and a 
question mark (?). If you have not specified a str-const, BASIC displays only the question 
mark. The program then waits for data. 


If chnl-exp does not correspond to a terminal, BASIC displays only the question mark. 


The LINPUT assigns all characters except the line terminator(s) to str-vb/. Single and double 
quotation marks, commas, tabs, leading and trailing spaces, or other special characters in 
the string are part of the data. 


If the RESUME statement transfers control to a LINPUT statement, the LINPUT statement 
retrieves a new record regardless of any data left in the previous record. 


After a successful LINPUT statement, the RECOUNT variable contains the number of bytes 
transferred from the file or terminal to the record buffer. 


If you terminate input text with CTRL/Z, BASIC assigns the value to the variable and signals 
“End of file on device’ (ERR= 11) when the next terminal input statement executes. If there 
is no next INPUT, INPUT LINE, or LINPUT statement in the program, the CTRL/Z is passed 
to BASIC as a signal to exit the BASIC environment. 


LINPUT “ENTER YOUR LAST NAME" +Last_names 


LINPUT #2%, Lastname 
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LSET 


Function 


The LSET statement assigns left-justified data to a string variable. LSET does not change the length of 
the destination string variable. 


Format 


| LSET str-vbl,... = str-exp | 


a ee er cnr Ee eo FE | 


Syntax Rules 
1. Str-vbl is the destination string. Str-exp is the string value assigned to str-vbl. 


2. BASIC evaluates str-vbi’s subscripts (if present) before evaluating str-exp. 


3.  Str-vbl cannot be a DEF function name unless the LSET statement is inside the multi-line 
DEF that defines the function. 


General Rules 


1. The LSET statement treats all strings as fixed-length. LSET neither changes the length of the 
destination string nor creates new storage. Rather, it overwrites the str-vbl’s current storage. 


2. If the destination string is longer than str-exp, LSET left-justifies str-exp and pads it with 
spaces on the right. If smaller, LSET truncates characters from the right of str-exp to match 
the length of str-vbl. 


Examples 
10 LSET ALPHA$=‘XYZ’ 
20 LSET AS,» BS = CODES + NA_MES 
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35.0 MAP 


Function 


The MAP statement defines a named area of statically allocated storage called a PSECT, declares data 
fields in the record, and associates them with program variables. 


Format 


MAP (map-nam) { [ data-type ] map-item }.... 


map-item: num-unsubs-vbi-nam 
num-array-nam ( int-const,... ) 
str-unsubs-vbl-nam [ = int-const ] 


str-array-nam ( int-const,... ) [ = int-const ] 
FILL [ ( int-const ) ] [ = int-const ] 

FILL% [ ( int-const ) ] 

FILL$ [ ( int-const ) ] [ = int-const ] 


Syntax Rules 


1. | Map-nam is global to the program and task. It cannot appear elsewhere in the program unit 
as a variable name. 


2. In VAX—-11 BASIC, map-nam can consist of from 1 to 31 characters. The first character of 
the name must be an alphabetic character (A through Z). The remaining characters, if 
present, can be any combination of letters, digits (0 through 9), dollar signs ($), periods (.), 
or underscores (_). 


3. In BASIC—PLUS—2, map-nam can consist of from one to six characters. The first character 
must be an alphabetic character (A through Z). The remaining characters, if present, can be 
any combination of letters, digits (0 through 9), dollar signs ($), or periods (.). 


4. Map-item declares the name and format of the data to be stored. 


e Num-unsubs-vbI-nam and num-arr-nam specify a numeric variable or a numeric array. 


® Str-unsubs-vbl-nam and str-arr-nam specify a fixed-length string variable or array. You 
can specify the number of bytes to be reserved for the variable with the =jint-const 
clause. The default string length is 16. 


@ The FILL, FILL%, and FILL$ keywords allow you to reserve parts of the record buffer 
within or between data elements and to define the format of the storage. Int-const speci- 
fies the number of FILL items to be reserved. The = int-const clause allows you to specify 
the number of bytes to be reserved for string FILL items. Table 21 describes FILL item 
format and storage allocation. 
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Note 


In the applicable formats of FILL, (int-const) represents a repeat count, not an 
array subscript. FILL (n), for example, represents n elements, not n + 1. 


Data-type can be any BASIC data-type keyword or, in VAX—11 BASIC, a data type defined 
by a RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2. 


When you specify a data-type, all following map-items, including FILL items, are of that 
data type until you specify a new data type. 


If you do not specify any data-type, map-items without a data-typing suffix character (% or 
$) take the current default data type and size. 


Variable names, array names, and FILL items following a data-type cannot end in a dollar 
sign or percent sign. 


Variables and arrays declared in a MAP statement cannot be declared elsewhere in the 
program by any other declarative statements. 


General Rules 


1. 


BASIC does not execute MAP statements. The MAP statement allocates static storage and 
defines data at compile time. 


A program can have multiple MAPs with the same name. The allocation for each MAP 
overlays the others. Thus, data is accessible in many ways. The actual size of the data area 
is the size of the largest MAP. When you link or task-build your program, the size of the 
MAP area is the size of the largest MAP with that name. 


Map-items with the same name can appear in different MAP statements with the same 
map-nam only if they match exactly in attributes such as data type, position, and so forth. 
If the attributes are not the same, BASIC signals an error. For example: 


100 MAP (ABC) LONG Aa; B 

200 MAP (ABC) LONG A+ C ! This MAP statement is valid 

300 MAP (ABC) LONG Bs; A ! This MAP statement produces an error 
400 MAP (ABC) WORD A+ B ! This MAP statement Produces an error 


Line 300 causes BASIC to signal the error ‘‘variable <name> not aligned in multiple 
references in MAP <name>’, while line 400 generates the error “attributes of overlaid 
variable <name< don’t match’’. 


The MAP statement should precede any reference to variables declared in it. 
Storage space for map-items is allocated in order of occurrence in the MAP statement. 


A MAP area can be accessed by more than one program module, as long as you define the 
map-nam in each module that references the MAP. 


A COMMON area and a MAP area with the same name specify the same storage area and: 
are not allowed in the same program module. 
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8. A MAP named in an OPEN statement’s MAP clause is associated with that file. The file’s 
records and record fields are defined by that MAP. The size of the MAP determines the 
record size for file 1/O, unless the OPEN statement includes a RECORDSIZE clause. 


9. VAX—11 BASIC does not initialize variables in the MAP statement. 
10. BASIC—PLUS-—2 initializes MAP variables to zero or a null string. 


Examples 
200 MAP (BUF1) BYTE AGE» STRING EMP_NAME = 20, SINGLE EMP_NUM 
400 MAP (BUF1) BYTE FILL+ STRING LAST_NAME = 12+ FILL = 8+ SINGLE FILL 


212 BASIC Reference Manual 


MAP DYNAMIC 


36.0 MAP DYNAMIC 


Function 


The MAP DYNAMIC statement names the variables and arrays whose size and position in a MAP 
buffer can change at run time. BASIC sets all variable and array element pointers to the beginning of 
the MAP buffer when the MAP DYNAMIC statement is processed. 


Format 


map-item: num-unsubs-vbl-nam 


num-array-nam ( int-const,... ) 


str-unsubs-vbl-nam 


str-array-nam ( int-const,... }) 


Syntax Rules 


1. Map-nam is the storage area named in a MAP statement. 


2. Map-item declares the name and data type of the items to be stored in the map buffer. All 
variable pointers point to the beginning of the map buffer until the program executes a 
REMAP statement. 


@ Num-unsubs-vbl-nam and num-arr-nam specify a numeric variable or a numeric array. 


@ Str-unsubs-vbl-nam and str-arr-nam specify a string variable or array. You cannot specify 
the number of bytes to be reserved for the variable in the MAP DYNAMIC statement. All 


etring items have a fivand_lanoth nf zarn 


til +h aAyvarciittac 2 DEMAD ctatarnant 
suing mem VE 4 iX€G-i€ngimM OF Zero Und ME Program Executes a REMAP statement. 


3. Data-type can be any BASIC data-type keyword or, in VAX—11 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manual. 


4. When you specify a data-type, all following map-items are of that data type until you 
specify a new data type. 


5. If you do not specify any data-type, map-items take the current default data type and size. 


6. Variable names and array names following a data-type cannot end in a dollar sign or 
percent sign suffix character. 


7. Variables and arrays declared in a MAP DYNAMIC statement cannot be declared else- 
where in the program by any other declarative statements. 


8. Map-items must be separated with commas. 
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General Rules 


1. The MAP DYNAMIC statement does not affect the amount of storage allocated to the map 
buffer declared in a previous MAP statement. Until your program executes a REMAP 
statement, all variable and array element pointers point to the beginning of the MAP buffer. 


2. BASIC does not execute MAP DYNAMIC statements. The MAP DYNAMIC statement 
names the variables whose size and position in the MAP buffer can change and defines 
their data type. 


3. If there is no MAP statement in the program unit with the same map-nam specified in the 
MAP DYNAMIC statement, BASIC signals the error ‘Insufficient space for MAP DYNAMIC 
variables in MAP <name>”. 


4. The MAP DYNAMIC statement must lexically precede the REMAP statement or BASIC 
signals the error ‘‘MAP variable <name> referenced before declaration’’. 


Examples 


100 MAP (MY.BUF) STRING DUMMY = S12 
MAP DYNAMIC (MY.BUF) STRING LAST; FIRST» MIDDLE, & 
BYTE AGE+ STRING EMPLOYER: & 
STRING CHARACTERISTICS 
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Function 


The MARGIN statement specifies the margin width for a terminal or for records in a terminal-format 
file. 


Format 


MARGIN [ chnl-exp, ] int-exp 
Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


2. Int-exp specifies the margin width. 


General Rules 
1. If you do not specify a chnl-exp, BASIC sets the margin on the controlling terminal. 
2. The file associated with chnl-exp must be an open terminal-format file. 


3.. BASIC signals the error ‘Illegal operation” (ERR = 141) if the file associated with chnl-exp 
is not a terminal-format file. 


4. If chnl-exp does not correspond to a terminal, and if int-exp is zero, BASIC sets the right 
margin to the size specified by the RECORDSIZE clause in the OPEN statement, if present. 
If no RECORDSIZE clause is present, BASIC sets the margin to the RMS blocksize. 


5. If chnl-exp is not present or if it corresponds to a terminal, and if int-exp is zero, BASIC sets 
the right margin to the size specified by the RECORDSIZE clause in the OPEN statement, if 
present. If no RECORDSIZE clause is present, BASIC sets the margin to the default terminal 
width. 


6. BASIC prints as much of a specified record as the margin setting allows on one line before 
going to a new line. Numeric fields are never split across lines. 


7. lf you specify a margin larger than the channel’s recordsize, BASIC signals an error. 


8. The MARGIN statement is in effect only while chn/-exp is open. When you close chnl-exp, 
BASIC returns to the default margin when you reopen the channel. 


Examples 


30 MARGIN #4; 132% 
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38.0 MAT 


Function 


The MAT statement lets you implicitly create and manipulate one- and two-dimensional arrays. You 
can use the MAT statement to assign values to array elements or to redimension a previously dimen- 
sioned array. You can also perform matrix arithmetic operations such as multiplication, addition, and 
subtraction, and other matrix operations such as transposing and inverting matrices. 


Format 


Initialization (Numeric) 


CON 
MAT num-array = IDN [ ( int-exp1 [, int-exp2 ] ) ] 
ZER 


Initialization (String) 


MAT str-array = NUL [ ( int-exp1 [, int-exp2 ] ) ] 


Array Arithmetic 


MAT num-array1 num-array2 | num-array3 
L \ 


J 


Scalar Multiplication 


MAT num-array4 ( num-exp ) * num-array5 


Inversion and Transposition 


TRN 
MAT num-array6 = { INV ( num-array7 ) 


Syntax Rules 
1. You cannot use the MAT statement on arrays of more than two dimensions. 


2. In VAX—171 BASIC, you cannot use the MAT statement on arrays of data-type DECIMAL or 
on arrays named in a RECORD statement. 


3. When initializing arrays, you can specify the array bounds. Int-exp7 and int-exp2 define 
the upper bounds of the array being implicitly created or the new dimensions of an existing 
array. 
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if you are creating an array, int-exp? and int-exp2 cannot exceed 10. 


¢ lf you do not specify bounds, BASIC creates the array and dimensions it to (10) or 
(10,10). 


e If you do specify bounds, BASIC creates the array with the specified bounds. If the 
bounds exceed (10) or (10,10), BASIC signals ‘‘Redimensioned array’’” (ERR= 105). 


To perform MAT operations on arrays larger than (10,10), create the input and output 
arrays with the DIM statement. 


When the array exists, the following rules apply: 


e If you specify bounds, BASIC redimensions the array to the specified size. However, 
MAT operations cannot increase the total number of array elements. 


e If you do not specify bounds, BASIC does not redimension the array. 


An array passed to a subprogram and redimensioned there by a MAT statement remains 
redimensioned when control returns to the calling program, with two exceptions: 


e When the array is within a RECORD and is passed BY DESC. 
e@ When the array is passed BY REF. 


Initialization 


1. 
Zs 


ofa 


CON sets all elements of num-array to one, except those in row and column zero. 


IDN creates an identity matrix from num-array. The number of rows and columns in 
num-array must be identical. IDN sets all elements to zero except those on the diagonal 
from num-array(1,1) to num-array(n,n), which are set to one. 


ZER sets all array elements to zero, except those in row and column zero. 


elements of a string array to the null string, except those in row and column 


Array Arithmetic 


bs 


The equals sign (=) assigns the results of the specified operation to the elements in 
num-array1]. 


If num-array3 is not specified, BASIC assigns the values of num-array2’s elements to the 
corresponding elements of num-array?. Num-array! must have at least as many rows and 
columns as num-array2. 


Use the plus sign (+) to add the elements of two arrays. Num-array2 and num-array3 must 
have identical bounds. 


Use the minus sign (—) to subtract the elements of two arrays. Num-array2 and num-array3 
must have identical bounds. 


Use the asterisk (*) to perform matrix multiplication on the elements of num-array2 and 
num-array3 and to assign the results to num-array1. This operation gives the dot product of 
num-array2 and num-array3. All three arrays must be two-dimensional, and the number of 
columns in num-array2 must equal the number of rows in num-array3. BASIC redimen- 
sions num-array7 to have the same number of rows as num-array2 and the same number of 
columns as num-array3. 
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Scalar 


4 
t. 


Multiplication 


BASIC multiplies each element of num-array5 by num-exp and stores the results in the 
corresponding elements of num-array4. 


Inversion and Transposition 


i 


TRN transposes num-array7 and assigns the results to num-array6. If num-array7 has 
m rows and n columns, num-array6 will have n rows and m columns. Both arrays must be 
two-dimensional. 


You cannot transpose a matrix to itself: MAT A = TRN(A) is invalid. 


INV inverts num-array7 and assigns the results to num-array6. Num-array7 must be a two- 
dimensional array that can be reduced to the identity matrix using elementary row opera- 
tions. The row and column dimensions must be identical. 


General Rules 


1. 


Examples 


You cannot increase the number of array elements or change the number of dimensions in 
an array when you redimension with the MAT statement. That is, you can redimension an 
array with dimensions (5,4) to (4,5) or (3,2), but you cannot redimension that array to (5,5) 
or to (10). The total number of array elements includes those in row and column zero. 


If an array is named in both a DIM statement and a MAT statement, the DIM statement 
must lexically precede the MAT statement. 


MAT statements do not operate on elements in: 1) the zero element (one-dimensional 
arrays) or 2) the zero row or column (two-dimensional arrays). MAT statements use these 
elements to store results of intermediate calculations. Therefore, you should not depend on 
values in row and column zero if your program uses MAT statements. 


Initialization (Numeric) 


100 


MAT CONVERT = ZER(10;10) 


Initialization (String) 


1000 


MAT NALME$ = NUL#(3+5) 


Array Arithmetic 


2000 


MAT NEWLINT = OLD_INT - RSLT_INT 


Scalar Multiplication 


3000 


MAT 240 = (4,24) * 2 


Inversion and Transposition 


4000 


MAT 9% = INY (24) 
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39.0 MAT INPUT 


Function 


The MAT INPUT statement assigns values from a terminal or terminal-format file to array elements. 


Format 


MAT INPUT [ chnl-exp, ] { array [ ( int-exp1 [, int-exp2 ] ) ] }.... 


Syntax Rules 


1. 


Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


The file associated with chni-exp must be an open terminal-format file. If chn/-exp is not 
specified, BASIC takes data from the controlling terminal. 


You cannot use the MAT INPUT statement on arrays of more than two dimensions. 


In VAX-11 BASIC, you cannot use the MAT INPUT statement on arrays of data-type 
DECIMAL or on arrays named in a RECORD statement. 


Int-exp1 and int-exp2 define the upper bounds of the array being implicitly created or the 
dimensions of an existing array. 


If you are creating an array, int-exp7 and int-exp2 cannot exceed 10. 


e If you do not specify bounds, BASIC creates the array, dimensions it to (10,10), and 
prompts only for the first array element. 


e If you do specify bounds, BASIC creates the array with the specified bounds. If the 


bounds exceed (10) or (10,10), BASIC signais ‘“‘Redimensioned array’’ (ERR= 105). 


To MAT INPUT to arrays iarger than (10,16), create the input and output arrays with the 
DIM statement. When the array exists, the following rules apply: 


e If you specify bounds, BASIC redimensions the array to the specified size. However, 
MAT INPUT cannot increase the total number of array elements. 


e If you do not specify bounds, BASIC does not redimension the array. 


General Rules 


1. 


The MAT INPUT statement prompts with a question mark on terminals open on channel 
zero only. 


Use commas to separate data elements and a line terminator to end the input of data. Use 
an ampersand before the line terminator to input data on more than one line. 


The MAT INPUT statement assigns values by row. That is, it assigns values to all elements 
in row one before beginning row two. 
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4, The MAT INPUT statement assigns the row number of the last data element transferred into 
the array to the system variable, NUM. 


5. The MAT INPUT statement assigns the column number of the last data element transferred 
into the array to the system variable, NUM2. 


6. If there are fewer elements in the input data than there are array elements, BASIC does not 
change the remaining array elements. 


7. If there are more data elements in the input stream than there are array elements, BASIC 
ignores the excess. 


8. Row zero and column zero are not changed. 
Examples 


1000 MAT INPUT EMP_NAME$(10+10) 
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40.0 MAT LINPUT 


Function 


The MAT LINPUT statement receives string data from a terminal or terminal-format file and assigns it 
to string array elements. 


Format 


MAT LINPUT [ chnl-exp, ] { str-array [ ( int-exp1 [, int-exp2 ] ) ] }.... 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


2. You cannot use the MAT LINPUT statement on arrays of more than two dimensions. 


3. In VAX-11 BASIC, you cannot use the MAT LINPUT statement on arrays of data-type 
DECIMAL or on arrays named in a RECORD statement. 


4. The file associated with chni-exp must be an open terminal-format file. If chn/-exp is not 
specified, BASIC takes data from the controlling terminal. 


5.  Int-exp1 and int-exp2 define the upper bounds of the array being implicitly created or the 
dimensions of an existing array. 


6. If you are creating an array, int-exp? and int-exp2 cannot exceed 10. 


e If you do not specify bounds, BASIC creates the array, dimensions it to (10,10), and 
prompts only for the first array element. 


a €HA Agade. (DiIaCIC eraatae pene the specific ae 
¢ lf you do specify bounds, BAS! the ified bounds. If the 


bounds eee? (10) or r (10, 10), aa oe pe ieleabe array’ (ERR= 105). 


7. To MAT LINPUT to arrays larger than (10,10), create the input and output arrays with the 
DIM statement. 


8. When the array exists, the following rules apply: 


e If you specify bounds, BASIC redimensions the array to the specified size. However, 
MAT LINPUT cannot increase the total number of array elements. 


¢ If you do not specify bounds, BASIC does not redimension the array. 


General Rules 


1. For terminals open on channel zero only, the MAT LINPUT statement prompts with a 
question mark for each string array element, starting with element (1,1). BASIC assigns 
values to all elements of row one before beginning row two. 


2. The MAT LINPUT statement assigns the row number of the last data element transferred 
into the array to the system variable, NUM. 
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3. The MAT LINPUT statement assigns the column number of the last data element transferred 
into the array to the system variable, NUM2. 


4. Typing only a line terminator in response to the question mark prompt causes BASIC to 
assign a null string to that string array element. 


5. MAT LINPUT does not change row and column zero. 
Examples 


400 MAT LINPUT TIME.CARD$(10%) 
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41.0 MAT PRINT 


Function 


The MAT PRINT statement prints the contents of a one- or two-dimensional array on your terminal or 
assigns the value of each array element to a record in a terminal-format file. 


Format 


MAT PRINT [ chnl-exp, ] { array [ ( int-exp1 [, int-exp2 ] ) ] [ sep ] }... 


: 


sep: 


Syntax Rules 


1. 


ion | 


Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


You cannot use the MAT PRINT statement on arrays of more than two dimensions. 


In VAX-11 BASIC, you cannot use the MAT PRINT statement on arrays of data-type 
DECIMAL or on arrays named in a RECORD statement. 


The file associated with chnl-exp must be an open terminal-format file. If you do not 
specify a chnl-exp, BASIC takes data from the controlling terminal. 


int-exp? and int-exp2 define the upper bounds of the array being implicitly created or the 
dimensions of an existing array. 


If the array does not exist, the following rules apply: 


e If you do not specify bounds, BASIC creates the array and dimensions it to (10,10). 


e If you do specify bounds, BASIC creates the array with the specified bounds. If the 
bounds exceed (10) or (10,10), BASIC prints (10) or (10,10) elements and signals 
“Subscript out of range’ (ERR = 55). 


When the array exists, the following rules apply: 


e If the specified bounds are smaller than the maximum bounds of a dimensioned array, 
BASIC prints a subset of the array, but does not redimension the array. For example, if 
you use the DIM statement to dimension A(20,20), and then MAT PRINT A(2,2), BASIC 
prints elements (1,1), (1,2), (2,1), and (2,2) only; array A(20,20) does not change. 


e If you do not specify bounds, BASIC prints the entire array. 
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8. Sep determines the output format for the array: 


e If you use a comma, BASIC prints each array element in a new print zone and starts each 
row on a new line. 


e If you use a semicolon, BASIC separates each array element with a space and starts each 
row on a new line. 


® If you do not use a sep character, BASIC prints each array element on its own line. 


9. When you use the MAT PRINT statement to print more than one array, each array name 
except the last must be followed with either a comma or a semicolon. BASIC prints a blank 
line between arrays. 


General Rules 
1. The MAT PRINT statement does not print elements in row or column zero. 


2. The MAT PRINT statement cannot redimension an array. 
Examples 


900 MAT PRINT #1+ TIME_CARD$(25) 5 
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42.0 MAT READ 


Function 


The MAT READ statement assigns values from DATA statements to array elements. 


Format 


MAT READ { array [ ( int-exp1 [, int-exp2 ] ) ] }.... 


Syntax Rules 


1. 


oe 


You cannot use the MAT READ statement on arrays of more than two dimensions. 


In VAX-11 BASIC, you cannot use the MAT READ statement on arrays of data-type 
DECIMAL or on arrays named in a RECORD statement. 


Int-exp1 and int-exp2 define the upper bounds of the array being implicitly created or the 
dimensions of an existing array. 


If you are creating an array, int-exp!? and int-exp2 cannot exceed 10. 


e If you do not specify bounds, BASIC creates the array and dimensions it to (10,10). 


e If you do specify bounds, BASIC creates the array with the specified bounds. If the 
bounds exceed (10) or (10,10), BASIC signals ‘‘Redimensioned array’’ (ERR=105). 


To MAT READ arrays larger than (10,10), create the array with the DIM statement. 


@ If you specify bounds, BASIC redimensions the array to the specified size. However, 
MAT READ cannot increase the total number of array elements. 


e If you do not specify bounds, BASIC does not redimension the array. 


General Rules 


1. 


The DATA statemenit(s) must be in the same program unit as the MAT READ statement. 


The MAT READ statement assigns data items by row. That is, it assigns data items to all 
elements in row one before beginning row two. 


The MAT READ statement does not read elements into row or column zero. 


The MAT READ statement assigns the row number of the last data element transferred into 
the array to the system variable, NUM. 
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5. The MAT READ statement assigns the column number of the last data element transferred 
into the array to the system variable, NUM2. 


6. If you MAT READ an existing array without specifying bounds, BASIC does not redimen- 
sion the array. If you MAT READ an existing array and specify bounds, BASIC redimen- 
sions the array. 

Examples 


100 MAT READ 2% 
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Function 
The MOVE statement transfers data between a record buffer and a list of variables. 


Format 


TO 
MOVE FROM chnl-exp, move-item.... 


move-item: num-vbl 
num-array ( [,]... ) 
str-vb] [ = int-exp ] 


str-array ([,]....) [ = int-exp ] 

{ data-type ] FILL [ ( int-exp ) ][ = int-const ] 
FILL% [ ( int-exp ) ] 

FILL$ [ ( int-exp ) ] [ = int-exp ] 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


Move-item specifies the variable or array to which or from which data is to be moved. 


Num-vbI and num-array specify a numeric variable or a numeric array. Parentheses indi- 
cate the number of dimensions in a numeric array. The number of dimensions is equai to 
the number of commas plus one. That is, empty parentheses indicate a one-dimensional 
array, One Comma indicates a two-dimensional array, and so on. 


4. Str-vbl and str-array specify a fixed length string variable or array. Parentheses indicate the 
number of dimensions in a string array. The number of dimensions is equal to the number 
of commas plus one. You can specify the number of bytes to be reserved for the variable or 
array elements with the =int-exp clause. The default string length for a MOVE FROM 
statement is 16. For a MOVE TO statement, the default is the string’s length. 


5. The FILL, FILL%, and FILL$ keywords allow you to transfer fill items of a specific data type. 
Table 21 shows FILL item formats, representations, and storage requirements. 


e If you specify a data-type before the FILL keyword, the fill is of that data type. If you do 
not specify a data-type, the fill is of the default data type. Data-type can be any BASIC 
data-type keyword or, in VAX—11 BASIC, a data type defined by a RECORD statement. 
Data-type keywords, size, range, and precision are listed in Table 2 in this manual. FILL 
items following a data-type cannot end in a dollar sign or percent sign. 


® Int-exp specifies the number of FILL items to be moved. 


e FILL% indicates integer fill. FILL$ indicates string fill. The =int-exp clause specifies the 
number of bytes to be moved for string FILL items. 
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6. 


Note 


ln the applicable formats of FILL, (int-exp) represents a repeat count, not an 
array subscript. FILL (n), for example, represents n elements, not n + 1. 


You cannot use an expression or function reference as a move-item. 


General Rules 


228 


1. 


Before a MOVE FROM statement can execute, the file associated with chnl-exp must be 
open and there must be a record in the record buffer. 


A MOVE statement neither transfers data to or from external devices, nor invokes the 
system Record Management Services. Instead, it transfers data between user areas. Thus, a 
record should first be fetched with the GET statement before using a MOVE FROM, and a 
MOVE TO should be followed by a PUT or UPDATE statement that writes the record to a 
file. 


MOVE FROM transfers data from the record buffer to the move-item. 
MOVE TO transfers data from the move-item to the record buffer. 


The MOVE statement does not affect the record buffer’s size. If a MOVE statement partially 
fills a buffer, the rest of the buffer is unchanged. If there is more data in the variable list 
than in the buffer, BASIC signals ‘“MOVE overflows buffer’ (ERR = 161). 


Each MOVE statement to or from a channel transfers data starting at the beginning of the 
buffer. For example: 


200 MOVE FROM #14; I[%+ AS = 1% 


In this example, BASIC assigns the first value in the record buffer to 1%; the value of 1% is 
then used to determine the length of A$. 


If a MOVE statement operates on an entire array: 


e BASIC transfers elements of row and column zero (contrast this with the MAT 
statements). 


@ The storage size of the array elements and the size of the array determine the amount of 
data moved. A MOVE statement that transfers data from the buffer to a longword integer 
array transfers the first four bytes of data into element (0,0), the next four bytes of data 
into element (0,1), and so on. 


If the MOVE TO statement specifies an explicit string length, the following restrictions 
apply: 


e If the string is equal to or longer than the explicit string length, BASIC moves only the 
specified number of characters into the buffer. 


e If the string is shorter than the explicit string length, BASIC moves the entire string and 
pads it with spaces to the specified length. 


BASIC does not check the validity of data during the MOVE operation. 
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990 MOVE FROM #4%+ RUNSZ,s HITS“, ERRORSZ; RBIZ; BAT. AVERAGE 


100 MOVE TO #9%+ FILL = 10%+ AS = 10% BS = 3O%+ CH = 2% 
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44.0 NAME AS 


Function 


The NAME AS statement changes the name of a specified file. 


Format 


NAME file-spec1 AS file-spec2 


Syntax Rules 
1. File-speci? and file-spec2 must be string expressions. 


2. There is no default for file type in file-spec1 or file-spec2. If the file to be renamed has a file 
type, file-spec1 must include both the file name and the file type. If you specify only a file 
name, BASIC searches for a file with no file type. If you do not specify a file type for 
file-spec2, BASIC names the file, but does not assign a file type. 


General Rules 


1. If the file specified by file-spec? does not exist, BASIC signals ‘‘Can’t find file or account’ 
(ERR=5). 


2. In VAX—11 BASIC and BASIC—PLUS—2 on RSX—-11M/M-—PLUS systems, file version num- 
bers are optional. BASIC renames the highest version of file-spec! if you do not specify a 
version number. 


oS) 


In VAX—11 BASIC and BASIC-PLUS—2 on RSX-11M/M-—PLUS systems, if you use the 
NAME AS statement on an open file, BASIC does not rename the file until you close it. 


Examples 


400 NAME "OUT.DAT" AS "RERUN,.DAT" 


500 NAME OLD_FILES AS NEW_FILES 
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Function 
The NEXT statement marks the end of a FOR, UNTIL, or WHILE loop. 


Format 


NEXT [ num-unsubs-vbl ] 


Syntax Rules 


1... Num-unsubs-vb! is required in a FOR loop and must correspond to the num-unsubs-vb! 
specified in the FOR statement. 


2. Num-unsubs-vbi is not allowed in an UNTIL or WHILE loop. 


General Rules 


1. Each NEXT statement must have a corresponding FOR, UNTIL, or WHILE statement or 
BASIC signals an error. 


Examples 


100 NEXT I% 
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46.0 NOMARGIN (VAX-11 BASIC) 


Function 


The NOMARGIN statement removes the right margin limit set with the MARGIN statement for a 
terminal or a terminal-format file. 


Format 


NOMARGIN [ chnl-exp ] 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


General Rules 
1. When you specify NOMARGIN, the right margin is set to 132. 
2. Chnl-exp, if specified, must be an open terminal-format file or a terminal. 
3. If you do not specify a chni-exp, BASIC sets the margin on the controlling terminal to 132. 
4 


The NOMARGIN statement applies to the specified channel only while the channel is 
open. If you close the channel and then reopen it, BASIC uses the default margin of 72. 


Examples 


1000 NOMARGIN #2% 
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ON ERROR GO BACK 


Function 
After BASIC executes an ON ERROR GO BACK in a subprogram or DEF, control transfers to the 
calling program when an error occurs. 


Format 


| ( ONERROR | | 
| | ON ERROR GO BACK | 


Syntax Rules 


None. 


General Rules 
1. The ON ERROR GO BACK statement is the default error handler for DEF functions. 


2. An ON ERROR GO BACK statement executed in the main program is equivalent to an 
ON ERROR GOTO 0 statement. 


3. If a main program calls a subprogram named SUB1, and SUB1 calls the subprogram 
named SUB2, an ON ERROR GO BACK statement executed in SUB2 transfers control to 
SUB1 when an error occurs in SUB2. If SUB1 also has executed an ON ERROR 
GO BACK statement, BASIC transfers control to the main program’s error handling 
routine. 

4. If there is no error outstanding, execution of am ON ERROR GO BACK statement causes 
subsequent errors to return control to the calling program’s error handler. 


5. If there is an error outstanding, execution of am ON ERROR GO BACK statement immedi- 
ately transfers control to the calling program’s error handler. 


6. The ON ERROR GO BACK statement remains in effect until the program unit completes 
execution or until BASIC executes another ON ERROR statement. 


Examples 
100 SUB LIST (A$) 


ON ERROR GOTO 19000 
OPEN AS FOR INPUT AS FILE #1 


400 LINPUT #1, Bé 
PRINT BS 


600 GOTO 4009 
! 


! 
! 
19000 IF (ERR = 11%) AND (ERL = 400%) 
THEN CLOSE #1% 
RESUME 32767 
ELSE ON ERROR GO BACK 
32767 SUBEND 
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48.0 ON ERROR GOTO 


Function 


The ON ERROR GOTO statement transfers program control to a specified line or label in the current 
program unit when an error occurs. 


Format 


ONERROR GO TO 


ON ERROR GOTO target 


Syntax Rules 
1. Target must exist in the same program unit as the ON ERROR GOTO statement. 
2.  Ifan ON ERROR GOTO is in a DEF, target must also be in that function definition. 


General Rules 


1. Execution of an ON ERROR GOTO statement causes subsequent errors to transfer control 
to the specified target. 


2. The ON ERROR GOTO statement remains in effect until the program unit completes 
execution or until BASIC executes another ON ERROR statement. 


3. BASIC does not allow recursive error handling. If a second error occurs during execution of 
an error-nandling routine, Control passes to the BASIC error handier and the program stops 


executing. 
Examples 
500 ON ERROR GOTO 9999 
B00 ON ERROR GOTO YES_ROUTINE 
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49.0 ON ERROR GOTO 0 


Function 


The ON ERROR GOTO 0 statement disables user error handling and passes control to the BASIC 
error handler when an error occurs. 


Format 


| ( Go To | | 


ONERROR | GOTO} o 


Syntax Rules 
None. 
General Rules 


1. If an error is outstanding, execution of an ON ERROR GOTO 0 statement immediately 
transfers control to the BASIC error handler. 


2. If there is no error outstanding, execution of an ON ERROR GOTO 0 statement causes 
subsequent errors to transfer control to the BASIC error handler. 


Examples 


19600 ON ERROR GOTO 0 
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50.0 ON GOSUB 


Function 


The ON GOSUB statement transfers program control to one of several subroutines, depending on the 
value of a control expression. 


Format 


ON int-exp GOSUB target,... [ OTHERWISE target ] 


Syntax Rules 


1. Target must exist in the current program unit. 


2. Control cannot be transferred into a statement block (such as FOR/NEXT, UNTIL/NEXT, 
WHILE/NEXT, DEF/END DEF, or SELECT/END SELECT). 


3. You can use the ON GOSUB statement in a statement block if ON GOSUB and all its 
targets are inside that statement block. 


General Rules 


1. Int-exp determines which target BASIC selects as the GOSUB argument. If int-exp equals 
one, BASIC selects the first target. If int-exp equals two, BASIC selects the second target, 
and so on. 


2. If there is an OTHERWISE clause, and if int-exp is less than one or greater than the number 
of targets in the list, BASIC selects the target of the OTHERWISE clause. 


3. If there is no OTHERWISE clause, and if int-exp is less than one or greater than the number 
of targets in the list, BASIC signals ‘‘ON statement out of range’ (ERR = 58). 


4. If a target specifies a nonexecutable statement, BASIC transfers control to the first execut- 
able statement that lexically follows the target. 


Examples 
150 ON CONTROL% GOSUB 100+200,300,400 
200 ON A% GOSUB 10000,12000,14000 OTHERWISE 21000 
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51.0 ON GOTO 


Function 


The ON GOTO statement transfers program control to one of several lines, depending on the value of 
a control expression. 


~ Format 


GO TO 
ON int-exp (| GOTO | _ target ,... [ OTHERWISE target ] 


Syntax Rules 
1. Target must exist in the current program unit. 


2. Control cannot be transferred into a statement block (such as FOR/NEXT, UNTIL/NEXT, 
WHILE/NEXT, DEF/END DEF, SELECT/END SELECT). 


3. You can use the ON GOTO statement in a statement block if ON GOTO and all its targets 
are inside that statement block. 


General Rules 


1. Int-exp determines which line number BASIC selects as the GOTO argument. If int-exp 
equals one, BASIC selects the first target. If int-exp equals two, BASIC selects the second 
target, and so on. 


2. If there is an OTHERWISE clause, and if int-exp is less than one or greater than the number 
of targets in the list, BASIC transfers control to the target of the OTHERWISE clause. 


3. If there is no OTHERWISE clause, and if int-exp is less than one or greater than the number 
of jline numbers in the list, BASIC signals ‘“ON statement out of range’’ (ERR = 58). 


4. If a target specifies a nonexecutable statement, BASIC transfers control to the first execut- 
able statement that lexically follows the target. 


Examples 


330 ON INDEX% GOTO 700;800;900 OTHERWISE 1000 
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52.0 OPEN 


Function 


The OPEN statement opens a file for processing. It transfers user-specified file characteristics to 
Record Management Services and verifies the results. 


Format 


FOR INPUT 
OPEN file-spec!1 | FOR OUTPUT AS [ FILE ]} chni-exp1 [, open-clause J... 


open-clause: VIRTUAL 
UNDEFINED 
[ ORGANIZATION ] INDEXED STREAM 
SEQUENTIAL VARIABLE 
RELATIVE FIXED 


NONE 
READ 
WRITE 
MODIFY 


MODIFY 
SCRATCH 


LIST 

RECORDTYPE FORTRAN 
NONE 
ANY 


APPEND 
READ 
ACCESS WRITE 


(continued on next page) 
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{ RECORDSIZE int-exp1 } 

{ FILESIZE int-exp2 } 

{ WINDOWSIZE int-exp3 \ (Except on RSTS/E) 

{ TEMPORARY } 

{ CONTIGUOUS } 

{ MAP map-nam } 

{ CONNECT chni-exp2 \ 

{ BUFFER int-exp4 } 

{ |USEROPEN Func-nam } 

{ DEFAULTNAME file-spec2 } 

{ EXTENDSIZE int-exp5 } (Except on RSTS/E) 

{ MODE int-exp6 } (BASIC-PLUS-2 only) 
{ CLUSTERSIZE int-exp7 } (BASIC-PLUS-2 on RSTS/E only) 
{ BLOCKSIZE int-exp8 } (Sequential files) 

{ NOREWIND } (Sequential files) 

{ NOSPAN \ (Sequential files) 

{ SPAN } (Sequential files) 


BUCKETSIZE int-exp9 \ (Relative and Indexed files) 
PRIMARY [ KEY ] key [ DUPLICATES ] + (Indexed files) 


ALTERNATE [ KEY ] key [ DUPLICATES ] [ CHANGES ] } (Indexed files) 


UNLOCK EXPLICIT } (VAX-11 BASIC only) 


str-unsubs-vbl 
int-unsubs-vbl 
decimal-unsubs-vbl 


( str-unsubs-vbl1 ,... str-unsubs-vbl8 ) 


February 1984 BASIC Reference Manual 239 


OPEN 


Syntax Rules 


240 


a 
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File-spec1 specifies the file to be opened and associated with chnl-exp7. It can be any valid 
string expression and must conform to your system’s rules for file specifications. BASIC 
passes these values to RMS without editing, alteration, or validity checks. 


e VAX—11 BASIC does not supply any default file specifications unless you include the 
DEFAULTNAME clause in the OPEN statement. 


e BASIC—PLUS—2 supplies the device as a default. If a device has been supplied in a 
previous OPEN statement, that device is used as the default. If there is no previous 
device, SY: is supplied as the default device. There is no default for the file type unless 
you include the DEFAULTNAME clause in the OPEN statement. 


The FOR clause determines how BASIC opens a file. 
e If you open a file FOR INPUT, the file must exist or BASIC signals an error. 


@ If you open a file FOR OUTPUT, BASIC creates the file if it does not exist. If the file does 
exist, VAX~17 BASIC and BASIC—PLUS—2 on RSX-11M/M-—PLUS systems create a new 
version of the file. BASIC-PLUS—2 on RSTS/E systems overwrites the existing file. 


e If you do not specify either FOR INPUT or FOR OUTPUT, BASIC tries to open an existing 
file. If there is no such file, BASIC creates one. 


Chni-exp is a numeric expression that specifies a channel number to be associated with 
file-spec. It can be preceded by an optional pound sign (#). 


@ In VAX—11 BASIC, chnl-exp must be in the range 1 to 99. 
© In BASIC-PLUS—2, chn!-exp must be in the range 1 to 12. 


The ORGANIZATION clause specifies the file organization. When present, it must precede 
all other clauses. When your OPEN statement has ORGANIZATION SEQUENTIAL, 
RELATIVE, or INDEXED, you get an RMS file. 


@ On VAX/VMS and RSX-11M/M-—PLUS systems, you get a terminal-format file when you 
omit the ORGANIZATION clause entirely. Terminal-format files are implemented as 
RMS sequential variable files and store ASCII characters in variable-length records. Car- 
riage control is performed by the operating system; the record does not contain carriage 
returns or line feeds. You use essentially the same syntax to access terminal-format files 
as when reading from or writing to the terminal (INPUT and PRINT). 


e On RSTS/E systems, when you omit the ORGANIZATION clause, you get a terminal- 
format file that is a native mode RSTS/E ASCII stream file. RSTS/E ASCII stream files 
contain embedded carriage control characters. That is, carriage return and line feed 
characters are part of the record. See BASIC on RSTS/E Systems for more information on 
RSTS/E native mode files. 


In the USEROPEN clause, func-nam must be a separately compiled FUNCTION subpro- 
gram and must conform to FUNCTION statement rules for naming subprograms. 


The key specified in the PRIMARY KEY or ALTERNATE KEY clause must be declared in the 
MAP statement referenced by the OPEN statement. 
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General Rules 


Te 
2. 


The OPEN statement does not retrieve records. 


Channel zero, the terminal, is always open. If you try to open channel zero, VAX—11 
BASIC signals the error ‘Illegal |/O channel’ (ERR=46) and BASIC—PLUS-2 signals ‘I/O 
channel already open at line <number>”. 


A statement that accesses a file cannot execute until you open that file and associate it with 
a chnl-exp. 
If a program opens a file 


tho nraviannchy ananad fil 
wie previdusry Gpericu tn 


n a channel 
and ns t 


The FOR clause does not specify how your program can use the file or how others can 

share it. The ACCESS clause specifies how you use the file and the ALLOW clause specifies 

how the file is shared. 

The ALLOW clause determines how other users can access the file: 

@ ALLOW NONE lets no other users access the file. This is the default if any ACCESS other 
than READ is specified. 


e ALLOW READ lets other users have READ access to the file. This is the default for 
ACCESS READ. 


@e ALLOW WRITE lets other users have WRITE access to the file. 
e ALLOW MODIFY lets other users have unlimited access to the file. 
The ACCESS clause determines how the program can use the file: 


e ACCESS READ allows only FIND, GET, or other input statements on the file. The OPEN 
statement cannot create a file if the ACCESS READ clause is specified. 


@ ACCESS WRITE allows only PUT, UPDATE, or other output statements on the file. 


nee 


e ACCESS MODIFY ailiows any I/O statement except SCRATCH on the file. ACCESS 
MODIFY is the default. 


@ ACCESS SCRATCH allows any I/O statement valid for a sequential or terminal-format 
file. 


e ACCESS APPEND is the same as ACCESS WRITE for sequential files, except that BASIC 
positions the file pointer after the last record when it opens the file. You cannot use 
ACCESS APPEND on relative or indexed files. 


The RECORDTYPE clause can be used only with RMS files. It specifies the file’s record 
attributes: 


e LIST specifies implied carriage control, <CR> <LF> in BASIC—PLUS—2, and <CR> in 
VAX—11 BASIC. This is the default for all file organizations except VIRTUAL. 


¢ FORTRAN specifies a control character in the record’s first byte. 
e NONE specifies no attributes. This is the default for VIRTUAL files. 


e ANY specifies a match with any file attributes when opening an existing file. If you create 
a new file, ANY is treated as LIST for all organizations except VIRTUAL. For VIRTUAL, it 
is treated as NONE. 
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9. The RECORDSIZE clause specifies the file’s record size: 
@ For ORGANIZATION FIXED, int-exp1 specifies the size of all records. 
@ For ORGANIZATION VARIABLE, int-exp1 specifies the size of the largest record. 


e If you specify both a RECORDSIZE and a MAP clause, the RECORDSIZE clause overrides 
the record size set by the MAP clause. If you specify a MAP but no RECORDSIZE, the 
record size is equal to the MAP size. If there is no MAP, the RECORDSIZE clause 
determines the record size. If there is no MAP or RECORDSIZE specified, BASIC uses the 
default record size for the file organization when creating the file. When a program 
opens an existing file, BASIC uses the file’s record size. 


@ When creating SEQUENTIAL files, BASIC supplies a default record size of 132. 
@ The record size is always 512 for VIRTUAL files unless you specify a RECORDSIZE. 


e If you do not specify a RECORDSIZE clause when opening an existing file, BASIC 
retrieves the record size value from the file. If you open a new file of ORGANIZATION 
RELATIVE and do not specify a RECORDSIZE clause, BASIC signals ‘‘Bad recordsize 
value on OPEN” (ERR= 148). 


10. The FILESIZE clause lets you pre-extend a new file to a specified size. The value of int-exp2 
is the initial allocation of disk blocks. The FILESIZE clause has no effect on an existing file. 


11.  Int-exp3 in the WINDOWSIZE clause lets you specify the number of block retrieval 
pointers you want to maintain in memory for the file. Retrieval pointers are associated with 
the file header and point to contiguous blocks on disk. By keeping retrieval pointers in 
memory, you can reduce the I/O associated with locating a record, as the operating 
system does not have to access the file header for pointers as frequently. The number 
of retrieval pointers in memory at any one time is determined by the system default 
or by the WINDOWSIZE clause. The usual default number of retrieval pointers on 
RSX—11M/M-PLUS and VAX/VMS systems is seven. 


@ On VAX/VMS systems, a value of 0 specifies the default number of retrieval pointers. A 
value of 255 means to map the entire file, if possible. Values between 128 and 254, 
inclusive, are reserved. 


@ On RSX-11M/M-—PLUS systems, you can specify up to 127 retrieval pointers. 

@ On RSTS/E systems the number of pointers in a window block is fixed at seven. Thus, 
you cannot use the WINDOWSIZE clause. You can, however, use the CLUSTERSIZE 
clause to increase the number of contiguous blocks mapped by one retrieval pointer. 


12. The TEMPORARY clause causes BASIC to delete the output file as soon as the program 
closes it. 


13. The CONTIGUOUS clause causes RMS to try to create the file as a contiguous sequence of 


disk blocks in BASIC~PLUS—2 and as a contiguous-best-try sequence of disk blocks in 
VAX—11 BASIC. The CONTIGUOUS clause does not affect existing files or nondisk files. 
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The MAP clause specifies that a previously declared map-nam is associated with the file’s 


record buffer. The MAP clause determines the record buffer’s address and length unless 
overridden by the RECORDSIZE clause. 


e The size of the largest MAP with the same map-nam in the current program unit becomes 
the file’s record size if the OPEN statement does not include a RECORDSIZE clause. 


e |f there is no MAP clause, the record buffer space that BASIC allocates is not directly 
accessible. Thus, MOVE statements are needed to access data in the record buffer. 


e You must have a MAP clause when creating an indexed file; you cannot use KEY clauses 


without MAP statements since keys serve as offsets into the buffer. 


The BUFFER clause can be used with all file organizations except UNDEFINED. For 
RELATIVE and INDEXED files, int-exp4 specifies the number of device or file buffers Rec- 
ord Management Services uses for file processing. For SEQUENTIAL files, int-exp4 speci- 
fies the size of the buffer; for example, BUFFER 8 for a SEQUENTIAL file sets the buffer size 
to eight 512—byte blocks. 


The USEROPEN clause lets you open a file with your own FUNCTION subprogram. 
Func-nam must conform to the FUNCTION statement rules for naming subprograms. 
BASIC calls the user program after it fills the FAB (File Access Block), the RAB (Record 
Access Block), and the XABs (Extended Attribute Blocks). The subprogram must issue the 
appropriate RMS calls, including $OPEN and $CONNECT, and return the RMS status as 
the value of the function. See the BASIC User’s Guide for more information on the 
USEROPEN routine. 


The DEFAULTNAME clause lets you supply a default file specification. If file-spec7 is nota 
complete file spec, file-spec2 in the DEFAULTNAME clause supplies the missing parts. For 
example: 

10 INPUT "FILE NAME" $FNAMS 

26 OPEN FNAMS FOR INPUT AS FILE #1i%) & 


DEFAULTNAME "“DB2:.DAT" 


If you type “ABC” for the file name, BASIC tries to open DB2:ABC.DAT. BASIC—PLUS—2 
allows DEFAULTNAME for RMS files only. 


The EXTENDSIZE clause lets you specify the increment by which Record Management 
Services extends a file after its initial allocation is filled. The value of int-exp5 is in 
512—byte disk blocks. 


The BLOCKSIZE clause specifies the physical blocksize of magnetic tape files. The value of 
int-exp8 is the number of records in a block. Thus, the block size in bytes is the product of 
the RECORDSIZE and the BLOCKSIZE value. The default BLOCKSIZE is one record. 


The NOREWIND clause controls tape positioning on magnetic tape files. If you specify 
neither ACCESS APPEND nor NOREWIND, the OPEN statement positions the tape at its 
beginning and then searches for the file. 


The NOSPAN clause specifies that sequential records do not cross block boundaries. SPAN 
specifies that records can cross block boundaries. SPAN is the default. This clause does not 
affect nondisk files. 
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22. The BUCKETSIZE clause applies only to relative and indexed files. It specifies the size of an 
RMS bucket. The value of int-exp9 is the number of records in a bucket. The default is one 
record. 


23. The PRIMARY KEY clause lets you specify an indexed file’s key. You must specify a 
PRIMARY KEY when opening an indexed file. The ALTERNATE KEY clause lets you specify 
up to 254 alternate keys. The ALTERNATE key clause is optional. 


e RMS creates one index list for each PRIMARY and ALTERNATE key you specify. These 
indexes are part of the file and contain pointers to the records. Each key you specify 
corresponds to a sorted list of record pointers. 


© The keys you specify determine the order in which records in the file are stored. All keys 
must be variables declared in the file’s corresponding MAP statement. The position of the 
key in the MAP statement determines its position in the record. The data type and size of 
the key are as declared in the MAP statement. 


e A key can be an unsubscripted string or WORD variable in BASIC—PLUS—2 and an 
unsubscripted string, WORD, LONG, or packed decimal variable in VAX—11 BASIC. 


e You can also create a segmented index key for string keys by separating the string 
variable names with commas and enclosing them in parentheses. You can then reference 
a segment of the specified key by referencing one of the string variables instead of the 
entire key. A string key can have up to eight segments. 


@ The order of appearance of keys determines key numbers. The PRIMARY KEY, which 
must appear first, is key zero. The first ALTERNATE KEY is one, and so on. 


@ DUPLICATES in the PRIMARY and ALTERNATE key clauses specifies that two records 
can have the same key value. If you do not specify DUPLICATES, the key value must be 
unique in all records. 


CHANGES in the ALTERNATE key clause specifies that you can change the value of an 
alternate key when updating records. If you do not specify CHANGES when creating the 
file, you cannot change the value of a key. You cannot specify CHANGES with the 
PRIMARY KEY clause. 


VAX-11 BASIC 


1. If you open a terminal-format file with RECORDTYPE NONE, you must explicitly insert 
carriage control characters into the records your program writes to the file. 


2. When you PRINT to a terminal-format file, you must supply a RECORDSIZE if the margin is 
to exceed 72 characters. For example, if you want to PRINT a 132-character line, specify 
RECORDSIZE 132 or use the MARGIN and NOMARGIN statements. 


3. The CONTIGUOUS clause does not guarantee that the file will occupy a contiguous disk 
area. If RMS can locate the file in a contiguous area, it will do so. However, if there is not 
enough free contiguous space for a file, RMS allocates the largest possible contiguous areas 
and does not signal an error. See the VAX—11 RMS User’s Guide for more information on 
contiguous disk allocation. 
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The CONNECT clause permits multiple record streams to be connected to the file. 


e The CONNECT clause must specify an INDEXED file already opened on chnl-exp2 with 
the primary OPEN statement. You cannot connect to a connected channel, only to the 
initially opened channel. You can connect more than one stream to an open channel. 


e All clauses of the two files to be connected must be identical except MAP, 
CONNECT, and USEROPEN. 


VAX—11 RMS does not allow the EXTENDSIZE clause for relative and indexed files. 


ATERIEN KI — — 


if you specify NOREWIND, the OPEN statement does not position the tape. Your program 
can search for records from the current position. 


The ALLOW clause can be used in the OPEN statement to specify file sharing of relative, 
indexed, sequential, and virtual files. But for sequential and virtual files, VAX—17 RMS 
restricts file sharing to files with fixed-length, 512—byte records. It does not allow the 
sharing of sequential files with variable-length records (the default), or of virtual files with 
recordsizes other than 512. 


The UNLOCK EXPLICIT clause allows you to explicitly lock records with GET and FIND 
statements. 


e The type of lock you impose on a record with GET or FIND remains in effect until you 
explicitly unlock the record or file with a FREE or UNLOCK statement or unti! you close 
the file. 


e If you specify UNLOCK EXPLICIT, and do not impose a lock on a record with GET or 
FIND, BASIC imposes the ALLOW NONE lock by default and the next GET or FIND does 
not unlock the previously locked record. 


e You must open a file with UNLOCK EXPLICIT before you can lock records with GET and 
FIND statements. See the sections on GET and FIND in this manual and Chapter 8 in 
BASIC on VAX/VMS Systems for more information on explicit record locking and unlock- 
ing. 

KEY clauses are optional for existing files if the keys in the file match BASIC defaults. If you 

do specify a key, it must match a key in the file. 


BASIC—PLUS—2 


1. 


The SRSANIZNON SEQUENTIAL STREAM clause specifies an RMS sequential stream 
file. 


On RSTS/E systems, you can create both RMS sequential stream and RSTS/E ASCII stream 

files: 

e If you specify ORGANIZATION SEQUENTIAL STREAM, the file is RMS sequential 
stream. 


e if you omit the ORGANIZATION clause entirely, the file is RSTS/E ASCII (that is, a 
RSTS/E terminal-format file). 


lf you specify a CONTIGUOUS clause and there is not enough free contiguous space, RMS 
signals an error. 
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The CONNECT clause in BASIC—PLUS-—2 establishes additional record access streams for 
RMS files that allow your program to process more than one record of a file at the same 
time. Each stream represents an independent and concurrently active sequence of record 
operations. 


e The CONNECT clause must specify a RELATIVE or INDEXED file already open on 
chnl-exp2. 


@ Each CONNECT established in a secondary OPEN statement uses another |/O channel. 
Because there are 12 |/O channels available, you can have a maximum of 12 connects 
to a file. 


e All clauses in the secondary OPEN statements must be identical except MAP, CON- 
NECT, and USEROPEN. 


e BASIC-PLUS—2 signals the error ‘Invalid file option’ (ERR=139) if your program 
attempts to connect to a record stream that is already connected to another stream. 


BASIC—PLUS—2 provides the MODE clause for non—RMS file operations. Int-exp6 specifies 
a MODE value. 


@ On RSX-11M/M-—PLUS systems, MODE is ignored except when your program is doing 
device-specific |/O to a magnetic tape. In this case, you can use MODE to set the tape 
density. In all other cases, RSX-11M/M-—PLUS systems ignore the MODE value. See 
BASIC on RSX—11M/M-—PLUS Systems for information on MODE values. 


@ On RSTS/E systems, MODE values affect only native-mode files, not RMS files. Further, 
MODE values have different meanings depending on the context in which you use them. 
This is because other pieces of software scan the MODE value to see which bits are set. 
For example, bit 14 may have one meaning to the RSTS/E terminal driver, another 
meaning to the file processor, and a third meaning to the diskette device driver. See 
BASIC on RSTS/E Systems for information on MODE values. 


BASIC—PLUS—2 on RSTS/E systems does not support the EXTENDSIZE clause. 


On RSTS/E systems, you can specify the smallest amount of contiguous disk space to be 
allocated when an RMS or RSTS/E native-mode file’s present allocation is exhausted. You 
do this with the CLUSTERSIZE clause. Int-exp7 must be a power of two. For example, a 
CLUSTERSIZE of eight means that each time the file requires more disk space, the RSTS/E 
operating system must have at least eight contiguous disk blocks to allocate. If the disk is 
fragmented, there may be no eight-block clusters, and BASIC—PLUS—2 signals the error 
“‘Nio room for user on device’. 


e The default size of the clusters is a disk pack parameter set when the disk pack is 
initialized or mounted. This parameter, called a CLUSTER (of 512—byte blocks), becomes 
the default CLUSTERSIZE (the smallest amount of disk space that can be allocated for any 
file operations on that disk pack). 


e The CLUSTERSIZE clause does not affect the number of blocks read or written. It speci- 
fies only the smallest amount of disk space that can be allocated to a file. 


@ VAX—11 BASIC and BASIC—PLUS—2 on RSX-11M/M-—PLUS systems do not support the 
CLUSTERSIZE clause; however, the EXTENDSIZE clause serves a similar function. 
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If you specify NOREWIND, the OPEN FOR OUTPUT statement positions the tape at the 
logical end of the tape. The program can then write records. The OPEN FOR INPUT 
statement searches for the specified file without rewinding. If the file is not found, BASIC 
rewinds the tape and searches for the file from the start of the tape. If the file is still not 
found, BASIC signals the error ‘File not found’’. 


Examples 


om 
cm 


OPEN "INPUT.DAT" FOR INPUT AS FILE #4; 
ORGANIZATION SEQUENTIAL FIXED: 
RECORDSIZE 200; 

MAP ABC; 
ALLOW MODIFY: ACCESS MODIFY 


Ge oo Ee 


200 OPEN Newfilet FOR OUTPUT AS FILE #3; 
ORGANIZATION INDEXED; 
MAP Emp_name: 
DEFAULTNAME "DB2:.DAT"; 
PRIMARY KEY Last# DUPLICATES: 
ALTERNATE KEY First# CHANGES 


100 MAP (SEGKEY) STRING LAST_NAME = 15, & 
FIRST.NAME = 15+ MI = 1 

200 OPEN "NAMES.IND" FOR OUTPUT AS FILE #1; 
ORGANIZATION INDEXED: 
PRIMARY KEY (LAST_NAME+ FIRST_NAME:s MI)+ 
MAP SEGKEY 


pe Ge 
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53.0 OPTION 
Function 


The OPTION statement allows you to set compilation qualifiers such as default data type, size, and 
scale factor. In VAX—17 BASIC, you can also set compilation conditions such as subscript checking, 
overflow checking, decimal rounding, and setup in a source program. The defaults affect only the 
program module in which the OPTION statement occurs. 


Format 


OPTION option-clause.... 


TYPE = type-clause 

SIZE = size-clause 
option-clause: SCALE = int-const 
ACTIVE 
INACTIVE 


(VAX-17 BASIC only) 
(VAX-71 BASIC only) 


= active-clause 


INTEGER 
REAL 
type-clause: EXPLICIT 
DECIMAL (VAX-11 BASIC only) 


size-clause: | size-tlem | 
| (size-item....) 
INTEGER int-clause 
size-item: REAL real-clause 
DECIMAL (d,s) (VAX-11 BASIC only) 
BYTE 
int-clause: WORD 
LONG 
SINGLE 
DOUBLE 
real-clause: GFLOAT { (VAX-17 BASIC only) 
HFLOAT | (VAX-11 BASIC only) 
active-clause: active-item 
(active-item,...) 
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[ey eee 
INTEGER OVERFLOW 


DECIMAL OVERFLOW 
active-item: SETUP 


(all VAX-11 BASIC only) 
DECIMAL ROUNDING 
SUBSCRIPT CHECKING 


Syntax Rules 


+; 


Option-clause specifies the compilation qualifiers to be in effect for the program module. 


e Type-clause sets the default data type for variables not explicitly declared in the program 
module. You can specify only one type-clause in a program module. 


@ Size-clause sets the default data subtypes for floating-point, integer, and (VAX—11 BASIC 
only) packed decimal data. Size-item specifies the data subtype you want to set. You can 
specify an INTEGER and/or REAL size-item in BASIC—PLUS—2 and an INTEGER, REAL, 
and/or DECIMAL size-item in VAX—11 BASIC. Multiple size-items in an OPTION state- 
ment must be enclosed in parentheses and separated by commas. 


e SCALE controls the scaling of double precision floating-point variables. Int-const speci- 
fies the power of 10 you want as the scaling factor. It must be an integer from 0 to 6, 
inclusive, or BASIC signals an error. See the SCALE command in Section II of this manual 
for more information on scaling. 


@ In VAX-11 BASIC, active-clause specifies the decimal rounding, integer and decimal 
overflow checking, setup, and subscript checking conditions you want in effect for the 
program module. Active-item specifies the conditions you want to set. Multiple 
active-items in an OPTION statement must be enclosed in parentheses and separated by 
commas. 


You can have more than one option in an OPTION statement, or you can use multiple 
OPTION statements in a program module. However, each OPTION statement must lexi- 
cally precede all other source code in the program module, with the exception of comment 
fields, REM, SUB, FUNCTION, and OPTION statements. 


General Rules 


1. 


OPTION statement specifications apply only to the program module in which the state- 
ment appears and affect all variables in the module, including SUB and FUNCTION 
parameters. 


BASIC signals an error in the case of conflicting options. For example, you cannot specify 
more than one type-clause or SCALE factor in the same program unit. 


If you do not specify a type-clause or a subtype-clause, BASIC uses the current environ- 
ment default data types. 


If you do not specify a scale factor, BASIC uses the current environment default scale 
factor. 
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5. In VAX—11 BASIC, ACTIVE specifies the conditions that are to be in effect for a particular 
program module. INACTIVE specifies the conditions that are not to be in effect for a 
particular program module. If a condition does not appear in an active-clause, VAX—11 
BASIC uses the current environment default for the condition. See Table 16 in this 
manual for information on the INTEGER-OVERFLOW, DECIMAL_OVERFLOW, SETUP, 
DECIMAL_ROUNDING, and SUBSCRIPT_CHECKING compilation qualifiers. These 
qualifiers correspond to active-clause conditions (INTEGER OVERFLOW, DECIMAL 
OVERFLOW, SETUP, DECIMAL ROUNDING, and SUBSCRIPT CHECKING). 


Examples 
10 FUNCTION REAL DOUBLE MONTHLY PAYMENT » & 
(DOUBLE INTEREST_RATE: & 
LONG NO_OF_PAYMENTS» & 
DOUBLE PRINCIPLE) 
20 OPTION TYPE = REAL; & 
SIZE = (REAL DOUBLE,» INTEGER LONG), & 


SCALE = 4 
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54.0 PRINT 


Function 


The PRINT statement transfers program data to a terminal or a terminal-format file. 


Format 


To the Controlling Terminal 


To a Channel 


PRINT chni-exp [, output-list ] 


output-list: [ exp ] [ sep [ exp ] J]... [ sep ] 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). If you do not specify a chnl-exp, 
BASIC prints to the controlling terminal. 


2. Output-list specifies the expressions to be printed and the print format to be used. 
3. Exp can be any valid expression. 


4. A sep character must separate each exp. The sep characters control the print format: 


e A comma iells BASIC to skip to the next print zone before printing the expression. 


eA semicolon tells BASIC to print the expression immediately after the previous 
expression. 


General Rules 
1. A terminal-format file must be open on the specified chnl-exp. 


2. APRINT line has an integral number of print zones. Note, though, that the number of print 
zones in a line differs from terminal to terminal. 


3. The right margin setting, if set by the MARGIN statement, controls the width of the PRINT 
line. 


4. The PRINT statement prints string constants and variables exactly as they appear, with no 
leading or trailing spaces. 
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5. BASIC prints quoted string literals exactly as they appear. Thus, you can print quotation 
marks, commas, and other characters by enclosing them in quotation marks. 


6. A PRINT statement with no output-list prints a blank line. 


7. An exp in the output-list can be followed by more than one sep character. That is, you can 
omit an exp and specify where the next exp is to be printed by the use of multiple sep 
characters. For example: 


100 PRINT "Name"++"Address and "S"City" 
Run 

PROGA 16-MAR-83 16:16 

Name Address and City 


In this example, the double commas after ‘“Name’’ cause BASIC to skip two print zones 
before printing ‘‘Address and ’’. The semicolon causes the next expression, ‘City’, to be 
printed immediately after the preceding expression. 


8. When printing numeric fields, BASIC precedes each number with a space or minus sign 
and follows it with a space. If a number can be represented exactly by six decimal digits or 
less, and, optionally, a decimal point, BASIC prints it that way. 


9. BASIC rounds a number with an integer portion of six decimal digits or less (for example, 
1234.567) to six digits (1234.57). If a number has more than six decimal digits, BASIC 
rounds the number to six digits and prints it in E format. 


10. BASIC does not print trailing zeros to the right of the decimal point. If all digits to the right 
of the decimal point are zeros, BASIC omits the decimal point as well. 


11. BASIC does not print more than six digits in explicit notation. If a number requires more 
than six digits, BASIC uses E format and precedes positive exponents with a plus sign (+). 


12. The PRINT statement can print up to: 
@ Three digits of precision for BYTE integers 
® Five digits of precision for WORD integers 
@ Six digits of precision for SINGLE floating-point numbers 
© Ten digits of precision for LONG integers 
e Sixteen digits of precision for DOUBLE floating-point numbers 
e Fifteen digits of precision for GFLOAT floating-point numbers (VAX—11 BASIC only) 
@ Thirty-three digits of precision for HFLOAT floating-point numbers (VAX—11 BASIC only) 
@ Thirty-one digits of precision for DECIMAL numbers (VAX—11 BASIC only) 
@ The string length for STRING values 
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13. A comma or semicoion can aiso follow the last item in output-list: 

@ When printing to a terminal, BASIC does not generate a line terminator after printing the 
last item. The next item printed with a PRINT statement is printed at the position speci- 
fied by the sep character following the last item in the first PRINT statement. 

@ When printing to a terminal-format file, BASIC does not write out the record until a 
PRINT statement without trailing punctuation executes. 

14. If no punctuation follows the last item in the output-list: 

e When printing to a terminal, BASIC generates a line terminator after printing the last 
item. 

@ When printing to a terminal-format file, BASIC writes out the record after printing the last 
item. 

15. If a string field does not fit on the current line: 

e When printing string elements to a terminal, BASIC prints as much as will fit on the 
current line and prints the remainder on the next line. 

e When printing string elements to a terminal-format file, BASIC prints the entire element 
on the next line. 

16. If a numeric field is the first field in a line, and the numeric field spans more than one line, 
BASIC prints part of the number on one line and the remainder on the next. Otherwise, 
numeric fields are never split across lines. If the entire field cannot be printed at the end of 
one line, the number is printed on the next line. 

17. When a number's trailing space does not fit in the last print zone, the number is printed 
without the trailing space. 

18. VAX—11 BASIC rounds a floating point number with a magnitude between 0.1 and 1.0 to 
six digits. For magnitudes smaller than 0.1, BASIC rounds the number to six digits and 
prints it in E format. 4 

19. For magnitudes smaller than 1, BASIC—PLUS—2 prints up to five leading zeros and six 
significant digits in explicit point unscaled notation. 

Examples 
100 PRINT "THE ANSWER IS "3SUM% 


200 PRINT #1, EMPLNUM;s EMP_NAME#$ EMP_AGE% 
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55.0 PRINT USING 


Function 


The PRINT USING statement generates output formatted according to a format string (either numeric 
or string) to a terminal or a terminal-format file. 


Format 


PRINT [ chnl-exp ] USING str-exp sep output-list 


output-list: [ exp ] [ sep [ exp ] ]... [ sep ] 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). If you do not specify a chnl-exp, 
BASIC prints to the controlling terminal. 


2.  Str-exp is the format string. It must contain at least one valid format field and must be 
followed by a sep character and at least one exp. 


3. Output-list specifies the expressions to be printed. 
® Exp can be any valid expression. 
@ A sep character must separate each exp. 


4. The sep characters in the PRINT USING statement do not control the print format as in the 
PRINT statement. 


General Rules 

1. The PRINT USING statement can print up to: 
© Three digits of precision for BYTE integers 
e Five digits of precision for WORD integers 
® Six digits of precision for SINGLE floating-point numbers 
© Ten digits of precision for LONG integers 
e Sixteen digits of precision for DOUBLE floating-point numbers 
e Fifteen digits of precision for GFLOAT floating-point numbers (VAX—11 BASIC only) 
@ Thirty-three digits of precision for HFLOAT floating-point numbers (VAX—11 BASIC only) 
e Thirty-one digits of precision for DECIMAL numbers (VAX—17 BASIC only) 
e The string length for STRING values 
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2. A terminal-format file must be open on the specified chni-exp or BASIC signals an error. 
3. PRINT USING rounds a floating-point number once. 


4. Format string characters control the format of numeric output. 


e The pound sign (#) reserves space for one sign or digit. 


e The comma (,) causes BASIC to insert commas before every third significant digit to the 
left of the decimal point. In the format field, the comma must be to the left of the 
decimal point, and to the right of the rightmost dollar sign, asterisk, or pound sign. A 
comma reserves space for a comma or digit. 


The period (.) inserts a decimal point. The number of reserved places on either side of 
the period determines where the decimal point appears in the output. 


¢ The hyphen (—) reserves space for a sign and specifies trailing minus sign format. If 
present, it must be the last character in the format field. It makes BASIC print negative 
numbers with a minus sign after the last digit, and positive numbers with a trailing 
space. The trailing minus sign format (—) can be used as part of a dollar sign ($$) format 
field. 


The letters CD enclosed in angle brackets (<CD>) print CR (Credit Record) after nega- 
tive numbers or zero and DR (Debit Record) after positive numbers. If present, it must 
be the last format in the format field. The (<CD>) format can be used as part of a dollar 
sign ($$) format field. 


e Four carets(“**) specify E notation for floating-point numbers. They reserve four places 
for SINGLE, DOUBLE, and VAX—11 BASIC GFLOAT values and five places for VAX—1 1 
BASIC HFLOAT values. If present, they must be the last characters in the format field. 


o 


Two dollar signs ($$) reserve space for a dollar sign and a digit and cause BASIC to print 
a dollar sign immediately to the left of the most significant digit. 


Two asterisks (+*) reserve space for two digits and cause BASIC to fill the left side of the 
numeric field with leading asterisks. 


A zero enclosed in angle brackets (<O>) prints leading zeros instead of leading spaces. 


A percent sign enclosed in angle brackets (<%>) prints all spaces in the field if the 
value of the print item is zero. 


Note 


When the dollar sign ($$), asterisk-fill («*), or zero-fill (<O>) formats are used to form 
one print field, they are mutually exclusive. Additionally, when the zero-fill (<O>) or 
blank-if-zero (<%>) formats are used to form one print field, they also are mutually 
exclusive. 


e An underscore (_) forces the next formatting character in the format string to be inter- 
preted as a literal. It affects only the next character. If the next character is not a valid 
formatting character, the underscore has no effect and will itself be printed as a literal. 
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5. BASIC interprets any other characters in a numeric format string as string literals. 


6. Depending on usage, the same format string characters can be combined to form one or 
more print fields within a format string. For example: 


e When a dollar sign ($$) or asterisk-fill (**) format precedes a pound sign (#) , it modifies 
the pound sign format. The ($$) or (**) reserves two places, and with the pound signs 
forms one print field. For example: 


**OS#H## forms one field and reserves five spaces 
REE He forms one field and reserves four spaces 


When these formats are not followed by a pound sign or a blank-if-zero (<%>) format, 
they reserve two places and form a separate print field. 


e When a zero-fill (<O>) or blank-if-zero (<%>) format precedes a pound sign (#), it 
modifies the pound sign format. The (<O>) or (<%>) reserves one place, and with the 
pound signs forms one print field. For example: 


**<O>H##HH#F forms one field and reserves five spaces 
“KY > HHH forms one field and reserves four spaces 


When these formats are not followed by a pound sign, they reserve one space and form 
a separate print field. 


When a blank-if-zero (<%>) format follows a dollar sign ($$) or asterisk-fill (**) format, 
it modifies the ($$) or (**) format string. The (<%>) reserves one space, and with the 
($$) or (**) format string forms one print field. For example: 


**$$<%>### forms one field and reserves six spaces 
HERA KY SHH forms one field and reserves five spaces 


When the (<%>) precedes a ($$) or (**), it reserves one space and forms a separate 
print field. 


7. In VAX—11 BASIC, the comma (digit separator), dollar sign (currency symbol), and deci- 
mal point (radix point) are the defaults for U.S. currency. The PRINT USING statement 
accesses the system-wide logical names for these symbols. To cause PRINT USING to 
format foreign currency, these logical names must be changed. 


8. For E notation, PRINT USING left-justifies the number in the format field and adjusts the 
exponent to compensate, except when printing zero. When printing zero in E notation, 
BASIC prints leading spaces, leading zeros, a decimal point, and zeros in the fractional 
portion if the PRINT USING string contains these formatting characters, and then the 
String ““E+00”. 


9. Zero cannot be negative. That is, if a small negative number rounds to zero, it is repre- 
sented as a positive zero. 
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If there are reserved positions to the left of the decimal point, and the printed number is 
less than one, BASIC prints one zero to the left of the decimal point and pads with spaces 
to the left of the zero. 


If there are more reserved positions to the right of the decimal point than fractional digits, 
BASIC prints trailing zeros in those positions. 


lf there are fewer reserved positions to the right of the decimal point than fractional digits, 
BASIC rounds the number to fit the reserved positions. 


If a number does not fit in the specified format field, BASIC prints ‘’%’’, followed by the 
number in PRINT format. 


Format string characters control string output. All format characters except the backslash 
and exclamation point must start with a single quote (‘). A single quote by itself reserves 
one character position. A single quote followed by format character(s) marks the begin- 
ning of a character format field and reserves one character position. 


Note 


VAX-11 BASIC accepts either upper— or lowercase string formatting characters. 
BASIC—PLUS—2 accepts only uppercase string formatting characters. 


e | reserves one character position. The number of Ls plus the leading single quote 
determines the field’s size. BASIC left-justifies the print expression and pads with spaces 
if the print expression is less than or equal to the field’s width. If the print expression is 
larger than the field, BASIC left-justifies the expression and truncates its right side to fit 
the field. 


eR reserves one character position. The number of Rs plus the leading single quote 
determines the field’s size. BASIC right-justifies the print expression and pads with 
spaces if the print expression is less than or equal to the field’s width. If the print 
expression is larger than the field, BASIC left-justifies the expression and truncates its 
right side to fit the field. 


e C reserves one character position. The number of Cs plus the leading single quote 
determines the field’s size. If the string does not fit in the field, BASIC truncates its right 
side. Otherwise, BASIC centers the print expression in this field. If the string cannot be 
centered exactly, it is offset one character to the left. 


e E reserves one character position. The number of Es plus the leading single quote 
determines the field’s size. BASIC left-justifies the print expression if it is less than or 
equal to the field’s width and pads with spaces. Otherwise, BASIC expands the field to 
hold the entire print expression. 


e Two backslashes (\ \) when separated by n spaces reserve n+2 character positions. 
PRINT USING left-justifies the string in this field. BASIC does not allow a leading 
quotation mark with this format. 


e An exclamation point (!) creates a 1—character field. The exclamation point both starts 
and ends the field. BASIC does not allow a leading quotation mark with this format. 
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Note 


The backslash and exclamation formatting characters are included for com- 
patibility with BASIC-PLUS. DIGITAL recommends that you do not use this 
type of character field for new program development. 


15. BASIC interprets any other characters in the format string as string literals and prints them 
exactly as they appear. 


16. Acomma or semicolon can also follow the last item in output-list: 


© When printing to a terminal, BASIC does not generate a line terminator after printing the 
last item. The next item printed with a PRINT statement is printed at the position speci- 
fied by the sep character following the last item in the first PRINT statement. 


@ When printing to a terminal-format file, BASIC does not write out the record until a 
PRINT statement without trailing punctuation executes. 


17. If no punctuation follows the last item in the output-list: 


@ When printing to a terminal, BASIC generates a line terminator after printing the last 
item. 


@ When printing to a terminal-format file, BASIC writes out the record after printing the last 


item. 
Examples 
500 PRINT USING "S$#He#,##-", 8892.33) -88.3+ A_VARIABLE 
300 PRINT #1 USING "’E"$ "NOW IS THE TIME FOR ALL GOOD MEN" 
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56.0 PUT 


Function 


The PUT statement transfers data from the record buffer to a file. PUT statements are valid on RMS 
sequential, relative, indexed, and block 1/O files. You cannot use PUT statements on terminal-format 
files, virtual array files, or files opened with ORGANIZATION UNDEFINED. 


Format 


PUT chnl-exp [ , RECORD num-exp ][ , COUNT int-exp ] 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


2. PUT with no RECORD clause writes data to an RMS sequential, relative, indexed, or block 
1/O file. 


e For sequential files, PUT adds a record at the end of the file. 


® For relative and block I/O files, PUT places the record in the empty cell pointed to by 
the Next Record Pointer. If the file is empty, the first PUT places a record in cell number 
one, the second in cell number two, and so on. 


e For indexed files, RMS stores records in order of ascending primary key value and 
updates all index keys. 


3. The RECORD clause allows you to randomly write records to a relative or block |/O file by 
specifying the record number. Int-exp must be between one and the maximum record 
number defined in the OPEN statement. 


4. Int-exp in the COUNT clause specifies the record’s size. If there is no COUNT clause, the 
record’s size is that defined by the MAP or RECORDSIZE clause (RECORDSIZE overrides 
MAP) in the OPEN statement. 


e If you write a record to a file with variable-length records, int-exp must be between zero 
and the maximum record size specified in the OPEN statement, inclusive. 


e If you write a record to a file with fixed-length records, the COUNT clause serves no 
purpose. If used, int-exp must equal the record size specified in the OPEN statement. 


@ In BASIC—PLUS-2, if int-exp equals zero, the entire record is written to the file. 


General Rules 


1. For sequential access, the file associated with chn/-exp must be open with ACCESS WRITE, 
MODIFY, SCRATCH, or APPEND. 


2. To add records to an existing sequential file, open it with ACCESS APPEND. If you are not 
at the end of the file when attempting a PUT to a sequential file, BASIC signals ‘’Not at end 
of file’ (ERR = 149). 
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Examples 


PUT 


For random access, the relative or block I/O file associated with chni-exp must be open 
with ACCESS WRITE or MODIFY. 


After a PUT statement executes, there is no Current Record Pointer. The Next Record 
Pointer is set as follows: 


© For sequential files, PUT sets the Next Record Pointer to the end-of-file. 


e For relative and block I/O files, a sequential PUT sets the Next Record Pointer to the 
Next Record plus one. A random PUT leaves the Next Record Pointer unchanged. 


© For indexed files, PUT leaves the Next Record Pointer unchanged. 


When you specify a RECORD clause, BASIC evaluates int-exp and uses this value as the 
relative record number of the target cell. 


@ If the target cell is empty or occupied by a deleted record, BASIC places the record in 
that cell. 


@ If there is a record in the target cell, the PUT statement fails, and BASIC signals the error 
“Record already exists’ (ERR= 153). 


If an existing record in an indexed file has a record with the same key value as the one you 
want to PUT to the file, BASIC signals the error ‘Duplicate key detected” (ERR = 134) if 
you did not specify DUPLICATES for the key in the OPEN statement. If you specified 
DUPLICATES, RMS stores the records in a first-in, first-out sequence. 


The number specified in the COUNT clause determines how many bytes are transferred 
from the buffer to a file: 


e If you have not completely filled the record buffer before executing a PUT, BASIC pads 
the record with nulls to equal the specified value. 


@ If the specified COUNT value is less than the buffer size, the record is truncated to equal 
the specified value 

The number in the COUNT clause must not exceed the size specified in the MAP 

or RECORDSIZE clause in the OPEN statement or BASIC signals ‘Size of record invalid” 

(ERR = 156). 


Although block I/O files are implemented through RMS on VAX/VMS systems and 
RSX—11M/M-—PLUS systems, when you write a record to a block I/O file, RMS does not 
perform the same error checking as with relative files. A PUT will write a record to a disk 
block specified in the RECORD clause, regardless of whether the block already contains a 
record. See Chapter 9 in the BASIC User’s Guide for more information on RMS block I/O 
files. See the RSTS/E Programming Manual for information on RSTS/E native-mode block 
I/O files. 


Sequential, Relative, Indexed, and Block I/O Files 


700 


PUT #3+ COUNT 35% 


Relative and Block I/O Files Only 


2000 


PUT #5, RECORD 133; COUNT 16% 
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57.0 RANDOMIZE 


Function 


The RANDOMIZE statement gives the random number function, RND, a new starting point. 


Format 


RANDOMIZE 


RANDOM 


Syntax Rules 
None. 
General Rules 


1. Without the RANDOMIZE statement, successive runs of the same program generate the 
same random number sequence. If you use the RANDOMIZE statement before invoking 
the RND function, the starting point changes for each run. Thus, a different random num- 
ber sequence appears each time. 

Examples 


43 RANDOMIZE 
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Function 


The READ statement assigns values from a DATA statement to variables. 


Format 


READ vbl.... 


Syntax Rules 


1. In VAX—11 BASIC, vb! cannot be a DEF function name, unless the READ statement is inside 
the multi-line DEF body. 


i) 


In BASIC-PLUS—2, vbl can be a DEF function name. If you assign a value to the DEF 
function name in this way, the next invocation of the function returns that value if it is not 
modified by the function body. 


3. If your program has a READ statement without DATA statements, BASIC signals a compile- 
time error. 


General Rules 


1. When BASIC initializes a program unit, it forms a data sequence of all values in all DATA 
statements. An internal pointer points to the first value in the sequence. 


2. When BASIC executes a READ statement, it sequentially assigns values from the data 
sequence to variables in the READ statement variable list. As BASIC assigns each value, it 
advances the internal pointer to the next value. 


WwW 


BASIC signals tha error “Orit af data’ ( (ERR= 


R7\ i 
ww uIw wv wut Vi ININTT™ Ys 7) 1 


READ statements. Extra data elements are ignored. 


4. The data type of the value must agree with the data type of the variable to which it is 
assigned or BASIC signals ‘‘Data format error’ (ERR=50). 


5. IF you READ a string variable, and the DATA element is an unquoted string, BASIC ignores 
leading and trailing spaces. If the DATA element contains commas, they must be inside 
quotation marks. 


6. BASIC evaluates subscript expressions in the variable list after it assigns a value to the 
preceding variable, and before it assigns a value to the subscripted variable. For example: 


100 READ A+ AS$(A) 
! 
| 
! 


300 DATA 10+ NELSON 


BASIC assigns the value 10 to variable A, then assigns the string ‘“NELSON” to array 
element A$(10). 
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Examples 
1000 READ A+ BA, Ce 
| 
| 
! 
2000 DATA 32.5+ 8+ ENDDATA 
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59.0 RECORD (VAX-11 BASIC) 
Function 


The RECORD statement lets you name and define data structures in a BASIC program and provides 
the BASIC interface to the VAX—-11 Common Data Dictionary (CDD). You can use the defined 
RECORD name anywhere a BASIC data-type keyword is valid. 


Format 


aa aaa Al | 


RECORD rec-nam 
rec-component 


END RECORD [ rec-nam ] 


data-type rec-item [ , [ data-type ] rec-item ] 
rec-component: group-clause 
variant-clause 


rec-item: unsubs-vbi [ = int-const ] 
array ( int-const,...) [ = int-const ] 
FILL [ ( int-const ) ] [ = int-const ] 


group-clause: GROUP group-nam [ ( int-const,... ) ] 


rec-component 


END GROUP [ group-nam } 


variant-clause: VARIANT 
case-clause 


END VARIANT 


case-clause: CASE 


[ rec-component ] 
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Syntax Rules 


te 


Each line of text in a RECORD, GROUP, or VARIANT block can have an optional line 
number. 


Data-type can be a BASIC data-type keyword or a previously defined rec-nam or 
group-nam. Table 2 lists and describes BASIC data-type keywords. 


If the data-type of a rec-item is STRING, the string is fixed-length. You can supply an 
optional string length with the =int-exp clause. If you do not specify a string length, the 
default is 16. 


Int-const in the group-clause specifies the number of times the GROUP block occurs in the 
RECORD data structure. 


General Rules 


264 


Rec-item must conform to the rules for naming BASIC variables. 


Variables and arrays in a record definition are also called elementary record components. 


The RECORD statement names and defines a data structure called a record template, but 
does not allocate any storage. When you use the record template as a data type in a 
statement such as DECLARE, MAP, or COMMON, you declare a record instance. This 
declaration of the record instance allocates storage for the RECORD. For example: 


1000 DECLARE EMPLOYEE EMP.REC 


This statement declares a variable named EMP_REC. EMP_REC is of the user-defined 
data type EMPLOYEE. 


Whenever you access an elementary record component, that is, a variable named in a 
RECORD definition, you do it in the context of the record instance. Therefore, rec-item 
names need not be unique in your program. For example, you can have a variable called 
FIRST_NAME in any number of different RECORD definitions. However, you cannot use a 
BASIC keyword as a rec-item name and you cannot have two variables or arrays with the 
same name at the same level in the RECORD or GROUP definition. 
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6. The declarations between the GROUP keyword and the END GROUP keywords are called 
a GROUP block. The GROUP keyword is valid only within a RECORD block. 


7. A repeated GROUP is similar to an array within the record as it is zero-based. Thus, a 
repeat-count of 10 actually specifies 11 repetitions of the named GROUP. 


8. The declarations between the VARIANT keyword and the END VARIANT keywords are 
called a VARIANT block. 


9. The amount of space allocated for a VARIANT field in a RECORD is equal to the space 
needed for the variant field requiring the most storage. A record component outside of this 
overlaid field determines which record variant is used. 


10. The rec-nam qualifies the group-nam and the group-nam qualifies the rec-item. You can 
access a particular rec-item within a record by specifying rec-nam::group-nam::rec-item. 
This specification is called a fully qualified reference. The full qualification of a rec-item is 
also called a component path name. 


11. The group-nam is optional in a rec-item specification unless there is more than one 
rec-item with the same name. For example: 


16 DECLARE EMPLOYEE EMP_REC 
i 
i 
J 
100 RECORD Address 
STRING Streets Citys States Zip 
END RECORD Address 
200 RECORD Employee 
GROUP Emep_name 
STRING First = 15 
STRING Middle = 
STRING Last = 15 
END GROUP Emrep_name 
ADDRESS Work 
ADDRESS Home 
END RECORD Employee 


You can access the rec-item ‘‘Last’’ by specifying only ‘‘“EMP_REC::Last’’ because only one 
rec-item is named ‘‘Last.’” However, if you try to reference ““EMP_REC::City’”, BASIC signals 
an error because “‘City’’ is an ambiguous field, a component of both ‘““Work’’ and ‘‘Home.”’ 
To access ‘‘City,’” you must specify either ‘/EMP_REC::Work::City’’ or 
“EMP_REC::Home::City.”’ 
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Examples 


1000 RECORD EMP_LWAGE_CLASS 
GROUP EMP NAME 
STRING Last = 15 
STRING First = 14 
STRING Middle = i 
END GROUP EMP_NAME 
GROUP EMP_ADDRESS 
STRING Street = 15 
STRING City = 26 
STRING State = 
DECIMAL(S:+0) Zi 
END GROUP EMP_ADDRESS 
STRING WAGE_CLASS = 2 
VARIANT 
CASE 
GROUP HOURLY 
DECIMAL(4:2) Hourly_wage 
SINGLE Regular_pay_ytd 
SINGLE Overtime_Pay_ytd 
END GROUP HOURLY 
CASE 
GROUP SALARIED 
DECIMAL(7;:2) Yearly_salary 
SINGLE Pay_rtd 
END GROUP SALARIED 
CASE 
GROUP EXECUTIVE 
DECIMAL(8:2) Yearly_salary 
SINGLE Pay_ytd 
SINGLE Exrenses_ytd 
END GROUP EXECUTIVE 
END VARIANT 
RD EMP_WAGE_CLASS 


Tf 


END RECO 
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60.0 REM 


Function 


The REM statement permits program documentation. 


Format 


REM [comment] 


Syntax Rules 


1. 
2: 


REM must be the only statement on the line or the last statement on a multi-statement line. 


Because the REM statement is not executable, you can place it anywhere in a program, 
except where other statements, such as SUB and END SUB, must be the first or last 
statement in a program unit. 


BASIC interprets every character between the keyword REM and the next line number as 
part of the comment. 


General Rules 


1. 


Examples 


300 


When the REM statement is the first statement on a line-numbered line, BASIC treats any 
reference to that line number as a reference to the next higher-numbered executable 
statement. 


The REM statement is similar to the comment field that begins with an exclamation point, 
with one exception: the REM statement must be the last statement on a multi-statement 
line. The exclamation point comment field can be ended with a line terminator and fol- 
lowed by a BASIC statement. See Section | of this manual for more information on the 
comment field. 


REM THIS IS A COMMENT 
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61.0 REMAP 


Function 
The REMAP statement defines or redefines the position in the record buffer of variables named in the 
MAP DYNAMIC statement. 


Format 


REMAP (map-nam) remap-item.... 


remap-item: num-vbl-nam 
num-array-nam ([ int-exp,... ] ) 
str-vbl-nam [ = int-exp ] 
str-array-nam ([ int-exp,... ]) [ = int-exp ] 


[ data-type ] FILL [ ( int-exp ) ] [ = int-exp ] 
FILL% [ ( int-exp ) J 
FILL$ [ ( int-exp ) ] [ = int-exp ] 


Syntax Rules 
1. Map-nam is the name of a map area declared in the MAP and MAP DYNAMIC statements. 


2. Remap-item names a variable, array, or array element declared in a preceding MAP 
DYNAMIC statement: 


@ Num-vbl-nam specifies a numeric variable or array element. Num-arr-nam () specifies an 
entire numeric array. 


© Str-vbIl-nam specifies a string variable or array element. Str-arr-nam () specifies an entire 
fixed-length string array. You can specify the number of bytes to be reserved for string 
variables and array elements with the =int-exp clause. The default string length is 16. 


3. Remap-item can also be a FILL item. The FILL, FILL%, and FILL$ keywords let you reserve 
parts of the record buffer. Int-exp specifies the number of FILL items to be reserved. The 
= int-exp clause allows you to specify the number of bytes to be reserved for string FILL 
items. Table 21 describes FILL item format and storage allocation. 


Note 


In the applicable formats of FILL, (int-const) represents a repeat count, not an 
array subscript. FILL (n), for example, represents n elements, not n + 1. 


4. All remap-items, except FILL items, must have been named in a previous MAP DYNAMIC 
statement, or BASIC signals an error. 
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Data-type can be any BASIC data-type keyword or, in VAX—11 BASIC, a data type defined 
in a RECORD statement. Data-type keywords, size, range, and precision are listed in Table 
2 in this manual. You can specify a data type only for FILL items. 


@ When you specify a data-type, all following FILL items are of that data type until you 
specify a new data type. 


e If you do not specify any data-type, FILL items take the current default data type and size. 


e FILL items following a data-type cannot end in a dollar sign or percent sign suffix 
character. 


Remap-items must be separated with commas. 


General Rules 


1. 


ve 


The REMAP statement does not affect the amount of storage allocated to the map area. 


Each time a REMAP statement executes, BASIC sets record pointers to the named map area 
for the specified variables from left to right. 


The REMAP statement must be preceded by a MAP DYNAMIC statements or BASIC signals 
the error ‘‘No such MAP area <name>’’. The MAP statement creates a named area of 
static storage, the MAP DYNAMIC statement specifies the variables whose positions can 
change at run time, and the REMAP statement specifies the new positions for the variables 
names in the MAP DYNAMIC statement. 


Until the REMAP statement executes, all variables named in the MAP DYNAMIC statement 
point to the first byte of the MAP area and all string variables have a length of zero. When 
the REMAP statement executes, BASIC sets the internal pointers as specified in the REMAP 
statement. For example: 


i100 MAP (DUMMY) STRING MAP_BUFFER = 356 
MAP DYNAMIC (DUMMY) LONG A+ STRING Bs SINGLE C(¢(7) 
REMAP (DUMMY) B=14+ A+ CO) 


The REMAP statement sets a pointer to byte 1 of DUMMY_MAP for string variable B, a 
pointer to byte 15 for LONG variable A, and pointers to bytes 19, 23, 27, 31, 35, 39, 43, 
and 47 for the elements in SINGLE array C. 


You can use the REMAP statement to redefine the pointer for an array element or variable 
more than once in a single REMAP statement. For example: 
100 MAP (DUMMY) STRING = 48 


MAP DYNAMIC (DUMMY) LONG A» B10) 
REMAP (DUMMY) BC)+ B(O) 


This REMAP statement sets a pointer to byte 1 in DUMMY_MAP for array B. Since array B 
uses a total of 44 bytes, the pointer for the first element of array B, B(O) points to byte 45. 
References to array element B(0) will be to bytes 45 through 48. Pointers for array elements 
1 through 10 are set to bytes 1, 4, 8, 12, and so forth. 


Because the REMAP statement is local to a program module, it affects pointers only in the 
program module in which it executes. 
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Examples 


100 MAP (EMPREC) STRING HAP_BUFFER = i100 
MAP DYNAMIC (EMPREC) STRING EMP_NAME > 
LONG BADGE_NO;+ 
STRING STREET:+ CITY+ STATE» 
WORD ZIP>+ 
STRING START_DATE 
REMAP (EMPREC) EMP_NAME = 20; 


BADGE_NO; 
STREET = 10, 
CITY = 10, 
STATE = 2: 
ZzIPys 


START.DATE = 8 


300 REMAP (EMPREC) EMP_NAME = 10; 
BADGE NO; 
STRING FILL = 32, 
WORD FILL» 
START.DATE = 8 
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RESTORE 


Function 


The RESTORE statement resets the DATA pointer to the beginning of the DATA sequence or sets the 
record pointer to the first record in a file. RESET is a synonym for RESTORE. 


Format 
| {RESET | | 
RESTORE [ chnl-exp [, KEY # int-exp ] ] 


Syniax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


2. Int-exp must be between zero and the number of keys in the file minus one, inclusive. 


General Rules 


1. The RESTORE statement is not allowed on virtual array files or on files opened on unit 
record devices. 


2. If you do not specify a chni-exp, RESTORE resets the DATA pointer to the beginning of the 
DATA sequence. 


3. RESTORE affects only the current program unit. Thus, executing a RESTORE statement in a 
subprogram does not affect the DATA pointer in the main program. 


4. If there is no chnl-exp, and the program has no DATA statements, RESTORE has no effect. 
5. The file specified by chnl-exp must be open. 


6. If chnl-exp specifies a magnetic tape file, BASIC rewinds the tape to the first record in the 
file. 


7. The KEY clause applies to indexed files only. It sets a new key of reference equal to int-exp 
and sets the Next Record Pointer to the first logical record in that key. 


8. For indexed files, the RESTORE statement without a KEY clause sets the Next Record 
Pointer to the first logical record specified by the current key of reference. If there is no 
current key of reference, the RESTORE statement sets the Next Record Pointer to the first 
logical record of the primary key. 


9. If you use the RESTORE statement on any file type other than indexed, BASIC sets the Next 
Record Pointer to the first record in the file. 


Examples 


400 RESTORE #7%+ KEY #4% 
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63.0 RESUME 


Function 


The RESUME statement marks an exit point from an error-handling routine. BASIC clears the error 
condition and returns program control to a specified line number or to the program block in which 
the error occurred. 


Format 


RESUME [ lin-num ] 


Syntax Rules 


1. Lin-num must exist within the same program unit as the RESUME statement. 


2. The RESUME statement cannot be used in a multi-line DEF unless the lin-num is also in 
the DEF function definition. 


General Rules 


1. The RESUME statement does not accept a label as an argument. Therefore, you should 
number lines that are to receive control from the error handler. 


2. When no lin-num is specified in a RESUME statement, BASIC transfers control based on 
where the error occurs. If the error occurs on a numbered line containing a single state- 
ment, BASIC atways transfers conirol to that statement. However, if the error occurs 
within a multi-statement line: 


e Within a FOR, WHILE, or UNTIL loop, BASIC transfers control to the first statement that 
follows the FOR, WHILE, or UNTIL statement. 


e Within a SELECT block, BASIC transfers control to the start of the CASE block in which 
the error occurs. 


e After a loop or SELECT block, BASIC transfers control to the statement that follows the 
NEXT or END SELECT statement. 


e If none of the above conditions occurs, BASIC transfers control back to the statement 
that follows the most recent line number or label. 


3. To simplify and clarify error handling, DIGITAL recommends that the RESUME statement 
always be used with lin-num. 
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Examples 


19100 


19990 


RESUME 


A RESUME statement with a specified lin-num transfers control to the first statement of a 


multi-statement line, regardless of which statement caused the error. 


A RESUME statement cannot transfer control out of the current program unit. Thus, a 
RESUME statement with no lin-num cannot terminate an error handler in the following 
situation: (1) the error handler is handling an error that occurred in a subprogram or an 
external function, and (2) the error was passed to the calling program’s error handler by 
an ON ERROR GO BACK statement or by default. 


The execution of a RESUME with no l/in-num is illegal if there is no error active. A 
RESUME with a Jin-num is always legal. After clearing the error condition, BASIC transfers 
control to the specified line. 


RESUME 300 


RESUME 
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64.0 RETURN 


Function 


The RETURN statement transfers control to the statement immediately following the most recently 
executed GOSUB or ON GOSUB statement in the current program unit. 


Format 
| RETURN | 
[| ee es | 


Syntax Rules 


1. RETURN is the last statement executed in a subroutine even if it is not the last statement in 
the subroutine. 


General Rules 


1. Execution of a RETURN statement before the execution of a GOSUB or ON GOSUB causes 
BASIC to signal ‘RETURN without GOSUB” (ERR=72). 


Examples 


800 RETURN 
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65.0 RSET 
Funciion 


The RSET statement assigns right-justified data to a string variable. RSET does not change a string 
variable’s length. 


Format 


RSET str-vbl,... = str-exp 


Syntax Rules 
1. BASIC evaluates the str-vb/ subscript expression (if present) before assigning values. 


2. Str-vbl cannot be a DEF function name, unless the RSET statement is inside the DEF 
function definition. 


General Rules 


1. The RSET statement treats strings as fixed-length. It does not change the length of str-vb/ nor 
does it create new storage locations. 


2. If str-vbil is ionger than str-exp, RSET right-justifies the data and pads it with spaces on the 
left. 


3. — If str-vbl is shorter than str-exp, RSET truncates str-exp on the left. 
Examples 


100 RSET 22% = "LMNOP" 
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66.0 


Function 


The SCRATCH statement deletes the Current Record and all following records in an RMS sequential 
file. 


Format 


| SCRATCH chni-exp . | 


Syntax Rules 


None. 


General Rules 


1. Before you execute the SCRATCH statement, the file must be opened with ACCESS 
SCRATCH. 


2. The SCRATCH statement applies to ORGANIZATION SEQUENTIAL files only. 
The SCRATCH statement has no effect on terminals or unit record devices. 


4. For disk files, the SCRATCH statement discards the current record and all that follow it in 
the file. The file is not physically shortened. 


5. For magnetic tape files, the SCRATCH statement overwrites the current record with two 
end-of-file marks. 


Examples 


600 SCRATCH #4% 
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67.0 SELECT 


Function 


The SELECT statement lets you specify an expression, a number of possible values the expression may 
have, and a number of alternative statement blocks to be executed for each possible case. The END 
SELECT keywords terminate the SELECT block. The code between SELECT and END SELECT is called 
a SELECT block, and the code between CASE statements is called a CASE block. 


Format 


SELECT exp1 


case-clause 


[ else-clause ] 
END SELECT 
case-cilause: CASE case-item.... 
[ statement ] ... 


case-item: { rel-op ] exp2 


| exp3 TO exp4 


else-clause: CASE ELSE 


[ statement ] ... 


Syntax Rules 


1. Exp is the expression to be tested against the case-clauses and the else-clause. It can be 
numeric or string. 


@ Case-clause consists of the CASE keyword followed by a case-item and statements to be 
executed when the case-item is true. 


e Flse-clause consists of the CASE ELSE keywords followed by statements to be executed 
when no previous case-item has been selected as true. 


2. Case-item is either an expression to be compared with exp/ or a range of values separated 
with the keyword TO. 


® Rel-op is a relational operator specifying how exp? is to be compared to exp2. If you do 
not include a rel-op, BASIC assumes the equals (=) operator. BASIC executes the state- 
ments in the CASE block when the specified relational expression is true. 
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@ Fvn2 and avnd crarify: rang nf nume = 


e Fxp3 and exp4 specify a range of numeric or string values separated by the keyword TO. 
Separate multiple ranges with commas. BASIC executes the statements in the CASE block 
when exp? falls within any of the specified ranges. 


A SELECT statement can have only one else-clause. The else-clause is optional and, when 
present, must be the last CASE block in the SELECT block. 


General Rules 


1. 


2. 


Examples 


100 


Each statement in a SELECT block can have its own line number. 


The SELECT statement begins the SELECT BLOCK and the END SELECT keyword 


Rew SUG VLELLY I BLOCK ang wie FND JLLLLY I Keyw 


it. BASIC signals an error if you do not include the END SELECT keywords. 


Each CASE keyword establishes a CASE block. The next CASE or END SELECT keyword 
ends the CASE block. 


You can nest SELECT blocks within a CASE or CASE ELSE biock. 


BASIC evaluates exp? when the SELECT statement is first encountered; BASIC then com- 
pares exp? with each case-clause in order of occurrence until a match is found or until a 
CASE ELSE block or END SELECT is encountered. 


The following conditions constitute a match: 
© Exp] satisfies the relationship to exp2 specified by rel-op. 


e Exp7 is greater than or equal to exp3, but less than or equal to exp4, greater than or equal 
to exp5 but less than or equal to exp6, and so on. 


When a match is found between exp? and a case-item, BASIC executes the statements in 
the CASE block where the match occurred. If ranges overlap, the first match causes BASIC 
to execute the statements in the CASE block. After executing CASE block statements, 
control passes to the statement immediately following the END SELECT keywords. 


If no CASE match occurs, BASIC executes the statements in the e/se-clause, if present, and 
then passes control to the statement immediately following the END SELECT keywords. 


If no CASE match occurs and you do not supply a case-else clause, control passes to the 
statement following the END SELECT keywords. 


SELECT AZ + Ba + CZ 
CASE = 100 
PRINT ‘THE VALUE IS EXACTLY 100’ 
CASE i TO 99 
PRINT ‘THE VALUE IS BETWEEN 1 AND 99’ 
CASE > 100 
PRINT ‘THE VALUE IS GREATER THAN 100’ 
CASE ELSE 
PRINT ‘THE VALUE IS LESS THAN 100’ 
END SELECT 
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68.0 SLEEP 


Function 


The SLEEP statement suspends program execution for a specified number of seconds or until a 
Carriage return is entered from the controlling terminal. 


Format 


SLEEP int-exp 


Syntax Rules 


1. In VAX-11 BASIC, int-exp must be between 0 and 2147483647, inclusive; if it is greater 
than 2147483647, BASIC signals the error “Integer error or overflow” (ERR=51). 


2. In BASIC—PLUS—2, int-exp must be between 0 and 32767, inclusive; if it is greater than 
32767, BASIC signals ‘Integer error’ and does not suspend program execution. 


General Rules 
1. Int-exp is the number of seconds BASIC waits before resuming program execution. 


2. Pressing the RETURN key on the controlling terminal cancels the effect of the SLEEP 
statement. 


Examples 


BO SLEEP 12704 


pa Se ee a ie 
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Function 


STOP 


The STOP statement halts program execution. 


Format 


STOP 


Syntax Rules 


None. 


General Rules 


1. 
2. 


STOP is valid anywhere in a program. 


The STOP statement does not close files. 


VAX—11 BASIC 


1. 


When a STOP statement executes in a program executed with the RUN command in the 
BASIC environment, BASIC prints the line number and module name associated with the 
STOP statement, then displays the BASIC prompt. In response to the prompt, you can type 
immediate mode statements, CONTINUE to resume program execution, or any valid com- 
piler command. See BASIC on VAX/VMS Systems for more information on immediate 
mode. 


When a STOP statement is in an executable image, the line number, module name, and a 
pound sign (#) prompt are printed. In response to the prompt, you can type CONTINUE to 
continue program execution cr EXIT to end the program. if the program module was 


compiled with the /NOLINE qualifier, no line number is displayed. 


BASIC—PLUS—2 
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When a STOP statement executes in a program executed with the RUN /DEBUG command 
or compiled with the /DEBUG qualifier, control passes to the BASIC-PLUS—2 debugger. 
The debugger prints the line number and module name associated with the STOP state- 
ment, then displays the pound sign (#) prompt. You can then use BASIC—PLUS—2 debugger 
commands to analyze and debug your program. See Part VI in this manual for information 
on BASIC-PLUS—2 debugger commands. Use the EXIT command to exit from the debugger 
and end the program. 


When a STOP statement executes in a program executed with RUN or compiled without 
the /DEBUG qualifier, the line number of the STOP statement and a pound sign (#) 
prompt are printed. In response to the prompt, you can type CONTINUE to continue 
program execution or EXIT to end the program. The EXIT command closes all files before 
leaving the program. 


Examples 


95 


STOP 
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70.0 SUB 


Function 


The SUB statement marks the beginning of a BASIC subprogram and specifies its parameters by 
number and data type. 


Format 


VAX-11 BASIC 


SUB sub-name [ pass-mech ] [ ( [ formal-param ],... ) ] 


[ statement ]... 


END SUB 
SUBEND 


BY DESC 
pass-mech: 
BY REF 
formal-param: unsubs-vbl-nam 
[ data-type ]{ array-nam ( (amass sedeeth [ = int-const ] [ pass-mech ] 


BASIC—PLUS—2 


SUB sub-name [ ( [ formal-param ],... ) ] 
[ statement J... 


END SUB 
SUBEND 


formal-param: unsubs-vbl-nam 
[ data-type ] 7 array-nam ( faa ead 


a 
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Sub-nam is the name of the separately compiled subprogram. 


Formal-param specifies the number and type of parameters for the arguments the SUB 
subprogram expects to receive when invoked. 


e Empty parentheses indicate that the SUB subprogram has no parameters. 


e Data-type specifies the data type of a parameter. If you do not specify a data type, 
parameters are of the default data type and size. When you do specify a data type, all 
following parameters are of that data type until you specify a new data type. Data-type 
keywords, size, range, and precision are listed in Table 2 in this manual. 


e lf you specify a datatype, unsubs-vbl-nam and array-nam cannot end in a percent sign 
(%) or dollar sign ($). 


The SUB statement must be the first statement in the SUB subprogram. 


Compiler directives and comment fields (!), because they are not BASIC statements, may 
precede the SUB statement. However, they cannot precede the subprogram’s first 
numbered line. Note that REM is a BASIC statement; therefore, it cannot precede the SUB 
statement. 


Every SUB statement must have a corresponding END SUB statement or SUBEND 
statement. 


Any BASIC statement except END, FUNCTION, END FUNCTION, or EXIT FUNCTION 
can appear in a SUB subprogram. 


VAX—11 BASIC 
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Sub-nam can consist of from 1 to 31 characters and must conform to the following rules: 


e The first character of an unquoted name must be an alphabetic character (A through Z). 
The remaining characters, if present, can be any combination of letters, digits (0 through 
9), dollar signs ($), periods (.), or underscores (_). 


@ A quoted name can consist of any combination of printable ASCII characters. 


Data-type can be any BASIC data-type keyword or a data type defined in the RECORD 
statement. 


If the data type is STRING, the =int-const clause allows you to specify the length of the 
string. If you do not specify.a string length, the default length is 16. 


Pass-mech specifies the parameter passing mechanism by which the subprogram receives 
arguments when called by non—BASIC programs. 


A pass-mech clause outside the parentheses applies by default to all SUB parameters. A 
pass-mech clause in the formal-param list overrides the specified default and applies only 
to the immediately preceding parameter. 


If you do not specify a pass-mech, the SUB program receives arguments by the default 
passing mechanisms, as shown in Table 19. 
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SUB 


Vi 


8. 


Parameters defined in formal-param must agree in number, type, ordinality, and 
pass-mech with the arguments specified in the CALL statement of the calling program. 


You can specify from 1 to 32 formal-params. 


BASIC—PLUS—2 


1. 


4. 


Sub-nam can consist of from one to six characters and must conform to the following rules: 


e The first character of an unquoted name must be an alphabetic character (A through Z). 
The remaining characters, if present, can be any combination of letters, digits (0 through 
9), dollar signs ($), or periods (.). 


e A quoted name can consist of any combination of alphabetic characters, digits, dollar 
signs ($), periods (.), or spaces. 


Data-type can be any BASIC data-type keyword. 


Parameters defined in formal-param must agree in number, type, and ordinality with the 
arguments specified in the CALL statement of the calling program. 


You can specify from one to eight formal-params. 


General Rules 
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1. 


All variables, except those named in MAP and COMMON statements and in DATA state- 
ments in a subprogram, are local to that subprogram. 


BASIC initializes local variables upon each entry to the subprogram as follows: 
@ Numeric variables are initialized to zero. 


® String variables are initialized to the null string. 


VAX-11 BASIC 
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SUB subprograms receive parameters BY REF or BY DESC. A SUB subprogram cannot 
receive any parameter BY VALUE. Table 19 lists and describes VAX—11 BASIC parameter 
passing mechanisms. 


© BY REF specifies that the subprogram receives the argument’s address. 


e BY DESC specifies that the subprogram receives the address of a VAX—11 BASIC descrip- 
tor. For information about the format of a VAX—171 BASIC descriptor for strings and 
arrays, see Appendix C in BASIC on VAX/VMS Systems. For information on other types 
of descriptors, see the VAX Architecture Handbook. 


By default, VAX—11 BASIC subprograms receive numeric unsubs-vbls BY REF and all other 
parameters BY DESC. You can override these defaults for strings and arrays with a BY 
clause: 


e If you specify a string length with the = int-const clause, you must also specify BY REF. If 


you specify BY REF and do not specify a string length, BASIC uses the default string 
length of 16. 


e If you specify array bounds, you must also specify BY REF. 
RECORD data structures are initialized to zero or the null string. 


VAX-11 BASIC subprograms may be called recursively. 
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1. You cannot specify how subprograms receive parameters in BASIC—PLUS—2. Numeric 
unsubs-vbls are received BY REF and string unsubs-vbls and entire arrays are received BY 
DESC. Table 20 lists and describes BASIC-PLUS—2 BASIC parameter passing mechanisms. 


e BY REF specifies that the subprogram receives the argument’s address. 


e BY DESC specifies that the subprogram receives the address of a BASIC—PLUS—2 descrip- 
tor. For information about the format of a BASIC-PLUS-—2 descriptor, see Appendix C in 
BASIC on RSX—11M/M-—PLUS Systems and BASIC on RSTS/E Systems. 


2. BASIC—PLUS—2 subprograms cannot be called recursively. 


Examples 
VAX—11 BASIC 


100 SUB SUBS BY REF (DOUBLE A>» B+ & 
STRING EMP_NAM = 20 BY DESC; & 
WAGE(20)) 
I 
I 
! 
960 END SUB 


BASIC—PLUS—2 


100 SUB SUBPRO (BYTE AGEs DOUBLE WAGE(20+20)+ STRING EMP_NAME) 
{ 


{ 
! 
900 END SUB 
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71.0 SUBEND 


Function 
The SUBEND statement is a synonym for END SUB. See the END statement for syntax rules. 


Format 


SUBEND 


END SUB 
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72.0 SUBEXIT 


Function 


The SUBEXIT statement is a synonym for the EXIT SUB statement. See the EXIT statement for syntax 
rules. 


Format 


( SUBEXIT | 
| ExIT suB | 
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73.0 UNLESS 


Function 


UNLESS modifies a statement. BASIC executes the modified statement only if a conditional expres- 
sion is false. 


Format 


statement UNLESS cond-exp 


Syntax Rules 


1. The UNLESS qualifier cannot be used on nonexecutable statements or on statements such 
as SELECT, IF, and DEF that establish a statement block. 


2. Cond-exp can be any conditional expression. 


General Rules 


1. BASIC executes the statement only if cond-exp is false (value zero). 
Examples 


100 PRINT "A DOES NOT EQUAL 3" UNLESS AZ = 3% 
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74.0 UNLOCK 


Function 


The UNLOCK statement unlocks the current record or bucket locked by the last FIND or GET 
statement. 


Format 


| UNLOCK chni-exp | 


eee Ce ee 


Syntax Rules 


1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


General Rules 
1. A file must be opened on chni-exp before UNLOCK can execute. 
2. The UNLOCK statement does not apply to files not on disk. 


3. If the current record is not locked by a previous GET or FIND statement, the UNLOCK 
statement has no effect and BASIC does not signal an error. 


4. The UNLOCK statement does not affect record buffers. 


5. After you execute the UNLOCK statement, you cannot UPDATE or DELETE the current 
record. 


Examples 


90 UNLOCK #10 
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75.0 UNTIL 


Function 


The UNTIL statement marks the beginning of an UNTIL loop or modifies the execution of another 
statement. 


Format 


Conditional 
UNTIL cond-exp 


[ statement ]... 


Statement Modifier 


statement UNTIL cond-exp 


Syntax Rules 
1. Cond-exp can be any valid relational or logical expression. 
Conditional 


1. A NEXT statement must end the UNTIL loop. 


General Rules 


Conditional 


1. BASIC evaluates cond-exp before each loop iteration. If the expression is false (value zero), 
BASIC executes the loop. If the expression is true (value nonzero), control passes to the first 
executable statement after the NEXT statement. 


Statement Modifier 


1. BASIC executes the statement repeatedly until cond-exp is true. 


Examples 
Conditional 
10 UNTIL A >= 5 
A=A+ .01 
TOTAL = TOTAL + 1 
NEXT 
Statement Modifier 
100 A = A + 1 UNTIL A = 200 
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76.0 UPDATE 


Function 


The UPDATE statement replaces a record in a file with a record in the record buffer. UPDATE is valid 
only on RMS sequential, relative, and indexed files. 


Format 


| UPDATE chnl-exp [ , COUNT int-exp ] | 
Oe | 


Syntax Rules 


1. 


Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 


Int-exp in the COUNT clause specifies the record’s size. 


In BASIC-PLUS-2, if int-exp equals zero, the entire record is written to the file. 


General Rules 


LE 


The file associated with chn/-exp must be a disk file opened with ACCESS MODIFY. 


Each UPDATE statement must be preceded by a successful GET or FIND operation or 
BASIC signals ‘‘No current record’”” (ERR = 131). Because FIND locates but does not 
retrieve records, you must specify a COUNT clause in the UPDATE statement when the 
preceding operation was a FIND. Int-exp in the COUNT clause must exactly specify the 
size of the oid record. 


After an UPDATE statement executes, there is no Current Record Pointer. The Next Record 
Pointer is unchanged. 


The length of the new record must be the same as that of the existing record for all files 
with fixed-length records. If the new record is larger than the existing record, BASIC 
truncates the right side of the new record to fit the existing record. If the new record is 
smaller than the existing record, the file gets corrupted. 


If you write a record to a sequential file with fixed-length records, int-exp in the COUNT 
clause must exactly match the size of the old record. 


For sequential files with variable-length records, the length of the new record must be the 
same as that of the existing record. 


e If you specify a COUNT clause, int-exp must match the size of the existing record. 


@ In the absence of a COUNT clause, UPDATE uses the record size set by the last success- 
ful GET on that channel. 
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UPDATE 


Examples 


100 


For relative files with variable-length records, the new record can be larger or smaller than 
the record it replaces. 


@ The new record must be smaller than or equal to the maximum record size set with the 
MAP or RECORDSIZE clause when the file was opened. 


e You must use the COUNT clause to specify the size of the new record if it is different 
from that of the record last accessed by a GET on that channel. 


For indexed files with variable-length records, the new record can be larger or smaller than 
the record it replaces. 


@ When an indexed file permits duplicate primary keys, an updated record must be the 
same length as the old one. 


@ When the program does not permit duplicate primary keys, the new record can be no 
longer than the maximum record size specified in the MAP or RECORDSIZE clause when 
the file was opened and must include at least the primary key field. 


@ An alternate key for the new record can differ from that of the existing record only if the 
OPEN statement for that file specified CHANGES for the alternate key. 


On RSTS/E systems, you can use UPDATE on native-mode files opened with mode 1 bit set 
(UPDATE mode). 


UPDATE #4, COUNT 32 
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WAIT 


Function 


The WAIT statement specifies the number of seconds the program waits for terminal input before 
signaling an error. 


Format 


| WAIT int-exp | 


a a ce a a en eee et ee 


Syntax Rules 


1. The WAIT statement must precede an INPUT, INPUT LINE, LINPUT, MAT INPUT, or MAT 
LINPUT statement, or it has no effect. 


2. In VAX-11 BASIC, int-exp must be between 0 and 2147483647, inclusive; if it is greater 
than 2147483647, BASIC signals the error ‘Integer error or overflow” (ERR=51). 


3. In BASIC—PLUS-—2, int-exp must be between 0 and 32767, inclusive; if it is greater than 
32767, BASIC signals ‘Integer error’ and the WAIT statement has no effect. 


General Rules 


1.  Int-exp is the number of seconds BASIC waits for input before signaling the error, 
“Keyboard wait exhausted’ (ERR = 15). 


2. After BASIC executes a WAIT statement, all input statements wait the specified amount of 
time before BASIC signals an error. 


3. WAIT 0 disables the WAIT statement. 


Examples 

50 WAIT GO 
INPUT "YOU HAVE SIXTY SECONDS TO TYPE YOUR NAME"$ NAMES 
WAIT 0 
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78.0 WHILE 


Function 


The WHILE statement marks the beginning of a WHILE loop or modifies the execution of another 
statement. 


Format 


Conditional 


WHILE cond-exp 


[ statement ]... 


Statement Modifier 


statement WHILE cond-exp 


Syntax Rules 
1. Cond-exp can be any valid relational or logical expression. 
Conditional 
1. A NEXT statement must end the WHILE loop. 
General Rules 
Conditional 


1. BASIC evaluates cond-exp before each loop iteration. If the expression is true (value non- 
zero), BASIC executes the loop. If the expression is false (value zero), control passes to the 
first executable statement after the NEXT statement. 


Statement Modifier 


1. BASIC executes the statement repeatedly as long as cond-exp is true. 


Examples 
Conditional 
10 WHILE X ¢ 100 
XY =X + SOR(X) 
NEXT 


Statement Modifier 


100 Kh = X“Z + 12% WHILE AX © 100% 
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PART V 


Functions 
ABS 
1.0 ABS 
Function 


The ABS function returns a floating-point number that equals the absolute value of a specified 
floating-point expression. 


Format 


real-vbl = ABS(real-exp) 


yntax Rules 


None. 


General Rules 


1. BASIC expects the argument of the ABS function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 


2. The returned floating-point value is always greater than or equal to zero. The absolute 
value of zero is zero. The absolute value of a positive number equals that number. The 
absolute value of a negative number equals that number multiplied by minus one. 


Examples 

400 A = ABS(-100 * G) 
410 B= -39,2 

420 PRINT ABS(B)+ A 
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2.0 ABS% 


Function 


The ABS% function returns an integer number that equals the absolute value of a specified integer 
expression. 


Format 


int-vbl = ABS%(int-exp) 


Syntax Rules 


None. 


General Rules 


1. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default integer size. 


2. The returned value is always greater than or equal to zero. The absolute value of zero is 
zero. The absolute value of a positive number equals that number. The absolute value of a 
negative number equals that number multiplied by minus one. 


Examples 

400 A = ABSZ(-100% * G2) 
410 B= -39 

420 PRINT ABSZ(B)> A 
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3.0 ASCIl 


Function 


The ASCII function returns the ASCII value (base 10) of a string’s first character. 


Format 


ASC 
ASCII 


int-vbl = (str-exp) 


Syntax Rules 


None. 


General Rules 
1. The ASCII value of a null string is zero. 


2. The ASCII function returns an integer value of the default size between O and 255, 
inclusive. 


Examples 


309 ASC_VAL = ASCIICEMP_NAM$) 
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4.0 ATN 


Function 


The ATN function returns the angle, in radians, of a specified tangent. 


Format 


real-vbl = ATN(real-exp) 


Syntax Rules 


None. 


General Rules 
1. ATN returns a value from —PI/2 through PI/2. 
2. The returned angle is expressed in radians. 


3. BASIC expects the argument of the ATN function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 


Examples 
150 ANGLE_RAD = ATN(T) 
160 ANGLE_DEG = ANGLE_RAD/(PI/180) 
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5.0 BUFSIZ 


Function 


The BUFSIZ function returns the buffer size, in bytes, of a specified channel. 


Format 


int-vbl = BUFSIZ(chnl-exp) 


Syntax Rules 
None. 
Generali Rules 


1. Chnl-exp is the channel expression of an open file. If the specified channel is closed, 
BUFSIZ returns zero. You cannot include a pound sign (#) in chnl-exp. 


2. In BASIC—PLUS—2, BUFSIZ of channel zero returns the current terminal width or, in a 
batch stream, 512. 


3. In VAX-17 BASIC, BUFSIiZ of channel zero always returns 132. 
4, Int-vbl is a WORD integer in BASIC—PLUS—2 and a LONG integer in VAX—77 BASIC. 


Examples 


100 A = BUFSI2Z(2) 
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6.0 CCPOS 


Function 


The CCPOS function returns the output record’s current character or cursor position on a specified 
channel. 


Format 


int-vbl = CCPOS(chni-exp) 


Syntax Rules 
None. 
General Rules 


1. Chnl-exp must specify an open file or terminal. You cannot include a pound sign (#) in 
chnl-exp. 


2. If chnl-exp is zero, CCPOS returns the current character position of the controlling 
terminal. 


3. The int-vb/ returned by the CCPOS function is of the default integer size. 


4. The CCPOS function counts only characters. If you use cursor addressing sequences such 
as escape sequences, the value returned will not be the cursor position. 


5. The first character position on a line is zero. 
Examples 


100 CHNLO = CCPOS (0) 
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7.0 CHR$ 


Wheoeoerste 


Function 


The CHR$ function returns a 1—character string that corresponds to the ASCII value you specify. 


Format 


str-vbl = CHR&(int-exp) 


Syntax Rules 
None. 
General Rules 


1. CHR$ returns the character whose ASCII value equals int-exp. If int-exp is greater than 255, 
BASIC treats it modulo 256. For example, CHR$(325) is the same as CHR$(69). 


2. BASIC treats all arguments as unsigned 8—bit integers in the range O to 255. Negative 
numbers are treated as the two’s complement (for example, —1 is treated as 255). 


3. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 


default size. 
Examples 
220 AS = CHRS(65) 
230 PRINT CHRS( VALUE) 
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8.0 COMP% 


Function 


The COMP% function compares two numeric strings and returns a minus one, zero, or one, depend- 
ing on the results of the comparison. 


Format 


int-vbl = COMP%(str-exp1, str-exp2) 


Syntax Rules 


1. Str-exp7 and str-exp2 are numeric strings. They can contain up to 60 ASCII digits and an 
optional decimal point and leading sign. 


General Rules 

1. If str-exp7 is greater than str-exp2, COMP% returns one. 

2. If the string expressions are equal, COMP% returns zero. 
3. If str-exp7 is less than str-exp2, COMP% returns minus one. 
4 


The value returned by the COMP% function is an integer of the default size. 


Examples 

400 NUM_STRING$S = "35" 

425 OLD.NUM_STRING$S = "33,1" 

450 ALPHA = COMPZ(NUM_STRING$+ OLD_NUM_STRING#) 
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COS 


Function 


The COS function returns the cosine, in radians, of an angle. 


Format 


Syntax Rules 
None. 
General Rules 
1. The returned value is between minus one and one. 


2. BASIC expects the argument of the COS function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 

Examples 


900 COSINE.ALPHA = COS(PI/2) 


| BASIC Reference Manual 301 


CTRLC 


10.0 CTRLC 


Function 


The CTRLC function enables CTRL/C trapping. When CTRL/C trapping is enabled, a CTRL/C typed 
at the terminal causes control to be transferred to the program’s error handler. 


Format 


int-vbl = CTRLC 


Syntax Rules 


None. 


General Rules 


1. 


After the CTRLC function is invoked, control passes to the error handler when BASIC 
encounters a CTRL/C. If there is no error handler in a program, the program aborts when 
BASIC encounters a CTRL/C. 


2. CTRL/C trapping is asynchronous; that is, BASIC suspends execution and signals 
“Programmable “C trap’’ (ERR=28) as soon as it detects a CTRL/C. Consequently, a 
statement can be interrupted while executing. A statement so interrupted may be only 
partially completed and variables may be left in an undefined state. 

3. BASIC can trap more than one CTRL/C error in a program as long as the error does not 
occur while the error handler is executing. If a second CTRL/C is detected while the error 
handler is processing the first CTRL/C, the program aborts. 

4. On RSX-11M/M-PLUS systems, the task that contains the CTRLC function must be able to 
attach to a terminal as soon as the CTRLC function is enabled. If another task is attached to 
the terminal, the task that enabled the CTRLC function terminates with a directive error. 

5. The CTRLC function always returns a value of zero. 

Examples 

10 ON ERROR GOTO 19000 

20 YR = CTRLC 

19000 IF (ERR = 28) THEN ¥Y% = CTRLC 
19010 RESUME 
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11.0 CVTS$$ 


Function 


The CVT$$ function is identical to the EDIT$ function. See the EDIT$ function for syntax and general 
rules. 


Note 


DIGITAL recommends that you use the EDIT$ function rather than the CVT$$ function 
for new program development. 


Format 


str-vbl = CVT$$(str-exp, int-exp) 


Examples 


100 AS = CVT$$(BS +48) 
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12.0 CVTxx 


Function 
Note 


CVT functions are supported only for compatibility with BASIC-PLUS. DIGITAL 
recommends that you use BASIC’s dynamic mapping feature or multiple MAP state- 
ments for new program development. 


The CVT$% function maps the first 2 characters of a string into a 16-bit integer. The CVT%$ function 
translates a 16—bit integer into a 2—character string. The CVT$F function maps a 4— or 8—character 
string into a floating-point variable. The CVTF$ function translates a floating-point number into a 4— 
or 8—byte character string. The number of characters translated depends on whether the floating-point 
variable is single- or double-precision. 


Format 


int-vbl CVT$%(str-vbl) 
str-vbl CVT%§(int-vbl) 


str-vbi CVTFS(reai-vbi) 


real-vbl = CVT$F(str-vbl) 


Syntax Ruies 


1. In VAX-11 BASIC, CVT functions reverse the order of the bytes when moving them to or 
from a string. Thus, you can mix MAP and MOVE statements, but you cannot use FIELD 
and CVT functions on a file if you also plan to use MAP or MOVE. 


General Rules 


CVT$% 
| 1. If the CVT$% str-vb! has fewer than two characters, BASIC pads the string with nulls. 
2. In VAX—11 BASIC, if the default data type is LONG, only two bytes of data are extracted 
from str-vbl; the high-order byte is sign-extended into a longword. 


3. The value returned by the CVT$% function is an integer of the default size. 
CVT %$ 
1. Only two bytes of data are inserted into str-vbl. 


2. If you specify a floating-point variable for int-vb/, BASIC truncates it to an integer of the 
default size. If the default size is BYTE and the value of int-vbl exceeds 127, BASIC signals 
an error. 
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CVTxx 


CVT$F maps four characters when the program is compiled with /SINGLE and eight char- 
acters when the program is compiled with /DOUBLE. 


If str-vb] has fewer than four or eight characters, BASIC pads the string with nulls. 


The real-vb/ returned by the CVT$F function is of the default floating-point size. In VAX—11 
BASIC, if the default size is GFLOAT or HFLOAT, BASIC signals the error ‘Floating CVT 
illegal for GFLOAT or HFLOAT’’. 


CVTF$ 


Examples 
1o 

20 

100 


1190 


The CVTF$ function maps single-precision numbers to a 4—character string and double- 
precision numbers to an 8—character string. 


BASIC expects the argument of the CVTF$ function to be a real-exp. When the argument is 
a real-exp, BASIC returns a value of the same floating-point size. When the argument is not 
a real-exp, BASIC converts the argument to the default floating-point size and returns a 
value of the default floating-point size. In VAX—11 BASIC, if the default floating-point size 
is GFLOAT or HFLOAT, BASIC signals the error ‘Floating CVT illegal for GFLOAT or 
HFLOAT”’. 


AZ = CUTS2ZCEMP_NAMES) 
AS = CUTAZSCAZ) 
A = CUTSFCEMP_NAMES) 


EMP_NAMES = CYTFS(A) 


Note 


DIGITAL does not recommend the CVTxx functions for new program development. 
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13.0 DATES 


Function 


The DATE$ function returns a string containing a day, month, and year in the form dd—Mmm-yy. 


Format 


str-vbl = DATES(int-exp) 


Syntax Rules 


1. Int-exp can have up to six digits in the form YYYDDD, where the “’Y”’ characters specify 
the number of years since 1970 and the ‘’‘D” characters specify the day of that year. 


2. You must fill all three of the ‘‘D’’ positions with digits or zeros before you fill the ‘‘Y’”’ 
positions. For example: 


e DATE$(121) returns the date 01—-May—70, day 121 of the year 1970. 
e DATE$(1201) returns the date 20-Jul-71, day 201 of the year 1971. 
© DATE$(12001) returns the date 01—Jan—82, day 1 of the year 1982. 
e DATE$(10202) returns the date 21-Jul-80, day 202 of the year 1980. 


3. If int-exp equals zero, DATE$ returns the current date. 


General Rules 


1. The str-exp returned by the DATE$ function consists of nine characters and expresses the 
day, month, and year in the form dd-Mmm-yy. 


2. If you specify an invalid date, such as day 385, results are undefined and unpredictable. 


3. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 


4. On RSTS/E systems, the form of the DATE$ function’s output can be changed to ISO 
format, yy.mm.dd, during the installation procedure, or to the format selected by the 
system manager at system start-up time. 


Examples 


300 PRINT DATE(9231) 
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14.0 DECIMAL (VAX-11 BASIC Only) 


Function 


The DECIMAL function converts a numeric expression or numeric string to the DECIMAL data type. 


Format 


decimal-vb| = DECIMAL(exp [, int-const1, int-consi2 ] ) 


Syntax Rules 


1.  Int-const1 specifies the total number of digits (the precision) and int-const2 specifies the 
number of digits to the right of the decimal point (the scale). If you do not specify these 
values, BASIC uses the d (digits) and s (scale) defaults for the DECIMAL data type. 


2.  Int-const! and int-const2 must be positive integers in the range 1 to 31, inclusive. 
Int-const2 cannot exceed the value of int-const!. 


3. Exp can be either a numeric expression or a numeric string. If a numeric string, it can 
contain up to 31 ASCII digits and an optional decimal point and leading sign. 


General Rules 
1. If exp is a string, BASIC ignores leading, trailing, and embedded spaces and tabs. 


2. The DECIMAL function returns a zero when a string argument contains only spaces and 
tabs, or when it is null. 


Examples 


-100 INPUT “enter a decimal value" IDEC_VALUE 
B = DECIMAL(DEC_ VALUE +3+2) 
PRINT Bs BECIMAL(CHOURLY_ PAY)? 
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15.0 DET 
Function 


The DET function returns the value of the determinant of the last matrix inverted with the MAT INV 
function. 


Format 


real-vb| = DET 


Syntax Rules 
None. 
General Rules 


1. When a matrix is inverted with the MAT INV statement, BASIC calculates the determinant 
as a by-product of the inversion process. The DET function retrieves this value. 


2. If your program does not contain a MAT INV statement, the DET function returns a zero. 


3. The value returned by the DET function is a floating-point value of the default floating- 


point size. 

Examples 

100 DETERMINANT = DET 
PRINT DET 
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16.0 DIFS$ 


Function 


DIF$ returns a string whose value is the difference between two numeric strings. 


Format 


sir-vbl = DIF§(str-exp1, str-exp2) 


Syntax Rules 


1. 


Str-exp1 and str-exp2 specify the numeric strings you want to process. They can contain up 


to 54 ASCII digits, an optional decimal point, and an optional leading sign. 


General Rules 


1. 
2 
a: 


5. 


Examples 


900 


BASIC subtracts str-exp2 from str-exp7 and stores the result in str-vbl. 
The difference between two integers takes the precision of the larger integer. 


The difference between two decimal fractions takes the precision of the more precise 
fraction, unless trailing zeros generate that precision. 


The difference between two floating-point numbers takes precision as follows: 
e The difference of the integer parts takes the precision of the larger part. 
e The difference of the decimal fraction part takes the precision of the more precise part. 


BASIC truncates leading and trailing zeros. 


RESULTS = DIF$("G776"5 "-455") 
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17.0 ECHO 


Function 


The ECHO function causes characters to be echoed at a terminal open on a specified channel. 


Format 


int-vbl = ECHO(chnl-exp) 


Syntax Rules 
None. 
General Rules 
1. Chnl-exp must specify a terminal. You cannot include a pound sign (#) in chnl-exp. 


2. The ECHO function is the complement of the NOECHO function; that is, ECHO disables 
the effect of ECHO and vice versa. 


3. The ECHO function has no effect on an unopened channel. 


4. The ECHO function always returns a value of zero. 


Examples 


100 Y = ECHO(O) 
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18.0 EDITS 


Function 
The EDIT$ function performs one or more string editing functions, depending on the value of its 
integer argument. 


Format 


str-vb] = EDITS(str-exp, int-exp) 


De a | 


Syntax Rules 


None. 
General Ruies 


1. BASIC edits str-exp to produce str-vbl. 


2. The editing that BASIC performs depends on the value of int-exp. Table 22 describes EDIT$ 
values and functions. 


3. All values are additive; that is, you can perform the editing functions of values 8, 16, and 
32 by specifying a value of 56. 


4. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 


Table 22: EDIT$ Values 


Discards each character’s parity bit (bit 7) 

Discards all spaces and tabs 

Discards all carriage returns, line feeds, form feeds, deletes, escapes, and nulls 
Discards leading spaces and tabs 

Converts multiple spaces and tabs to a single space 


Converts lowercase letters to uppercase letters 


Converts left bracket ([) to left parenthesis [(] and right bracket (]) to right parenthesis [)] 


Discards trailing spaces and tabs (same as TRM$ function) 


Suppresses all editing for characters within quotation marks; if the string has only one quotation mark, BASIC 
suppresses all editing for the characters following the quotation mark 


Examples 


100 NEW_STRINGS = EDITS$(OLD_STRING$;, 32 + 16) 
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19.0 ERL 


Function 


The ERL function returns the number of the line where the last error occurred. 


Format 


int-vbl = ERL 


Syntax Rules 


None. 


General Rules 


1. If the ERL function is used before an error occurs or after BASIC executes a RESUME 
statement, results are undefined. 


2. The ERL function overrides the /NOLINE qualifier. If a program compiled with the 
/NOLINE qualifier in effect contains an ERL function, BASIC signals the message ‘’ERL 
overrides NOLINE”’. 


3. The int-vbl returned by the ERL function is a WORD integer in BASIC—PLUS—2 and a 
LONG integer in VAX—11 BASIC. 


Examples 
300 IF (ERL = 70) THEN RESUME 500 
' 
! 
1 
500 PRINT ‘Error occurred on line’sERL 
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ERNS 


Function 


The ERN$ function returns the name of the main program, subprogram, or (VAX—11 BASIC only) DEF 
that was executing when the last error occurred. 


Format 


Syntax Rules 
None. 


General Rules 


1. In BASIC—PLUS—2, if the ERN$ function executes before an error occurs, ERN$ is unde- 
fined. When an error occurs, ERN$ is set to the name of the module that caused the error. 


2. On VAX-11 systems, if the ERN$ function executes before an error occurs or after BASIC 
executes a RESUME statement, ERN$ returns a null string. 


Examples 


2000 PRINT ‘Error in module’sERN¢ 
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21.0 ERR 


Function 


The ERR function returns the number of the latest run-time error. 


Format 


int-vbl = ERR 


Syntax Rules 


None. 


General Rules 


1. If the ERR function is used before an error occurs or after BASIC executes a RESUME 
statement, results are undefined. 


2. The int-vbl returned by the ERR function is always a WORD integer in BASIC—PLUS—2 and 
a LONG integer in VAX—11 BASIC. 


3. Appendix B in BASIC on VAX/VMS Systems, BASIC on RSX—11M/M-—PLUS Systems, or 
BASIC on RSTS/E Systems lists run-time errors and their numbers. 


Examples 


2000 TF (ERR = 11) THEN RESUME 1009 
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22.0 ERTS 


Function 


The ERT$ function returns explanatory text associated with an error number. 


Format 


Syntax Rules 


None. 


General Rules 
1. Int-exp is an error number. It must be between 0 and 255, inclusive. 


2. The ERT$ function can be used at any time to return the text associated with a specified 
error number. 


3. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 


Examples 


2020 PRINT ‘’Error’sERR'S’ on line’ §ERL 
PRINT ERTSC(CERR) 
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23.0 EXP 


Function 


The EXP function returns the value of the mathematical constant ‘‘e’”’, raised to a specified power. 


Format 


real-vbl = EXP(real-exp) 


Syntax Rules 


None. 


General Rules 
1. The EXP function returns the value of ‘‘e” raised to the power of real-exp. 


2. When the default size is SINGLE or DOUBLE, EXP allows arguments between —88 and 88, 
inclusive. In VAX—11 BASIC, if the default size is GFLOAT, EXP allows arguments in the 
range —709 to 709, inclusive; if the default size is HFLOAT, the arguments can be in the 
range —11356 to 11355. When the argument exceeds the upper limit of a range, BASIC 
signals an error. When the argument exceeds the lower limit of a range, the EXP function 
returns zero and BASIC does not signal an error. 


3. BASIC expects the argument of the EXP function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 


Examples 


100 A = EXP(4.6) 
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24.0 FIX 


Function 


The FIX function truncates a floating-point value at the decimal point and returns the integer portion 
represented as a floating-point value. 


Format 


| real-vbl = FIX(real-exp) | 


a ee 


Syntax Rules 


None. 


General Rules 
1. The FIX function returns the integer portion of a floating-point value, not an integer value. 


2. BASIC expects the argument of the FIX function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 


3. If real-exp is negative, FIX returns the negative integer portion. For example, FIX(—5.2) 


returns —5. 
Examples 
200 FIX VALUE = FIX(-3,.333) 
710 PRINT FIX(24.566)+ FIX_VALUE 


BASIC Reference Manual 317 


FORMATS 


25.0 FORMATS 
Function 
The FORMATS$ function converts an expression to a formatted string. 


Format 


str-vb] = FORMATS$(exp, str-exp) 


Syntax Rules 


None. 


General Rules 


1. The rules for building a format string are the same as those for printing numbers with the 
PRINT USING statement. 


Examples 


300 PRINT FORMAT$(12345, "#8 ,##2") 
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26.0 FSPS$ 


Function 


The FSP$ function returns a string describing an open file on a specified channel. 


Format 


str-vbl = FSP§(chnl-exp) 


Syntax Rules 
1. A file must be open on chal-exp. You cannot include a pound sign (#) in chni-exp. 


2. The FSP$ function must come immediately after the OPEN statement for the file. 


General Rules 


1. In BASIC-PLUS—2, byte 1 returns the RMS record format field (RFM). In VAX—17 BASIC, 
byte 1 is undefined. 


2. In BASIC-PLUS—2, bytes 9 and 10 in the returned string contain the RMS Bucketsize (BKS) 
or RMS Blocksize (BLS) for magnetic tape. Byte 12 is the number of indexes (keys) in the 
file. In VAX—11 BASIC, the FSP$ function returns zeros in bytes 9 through 12. 


3. Use the FSP$ function with files opened as ORGANIZATION UNDEFINED. Then use 
multiple MAP statements to interpret the returned data. 


4. See the BASIC User’s Guide and the RMS User’s Guide for more information on FSP$ 
values. 


Note 


VAX—11 BASIC supports the FSP$ function for compatibility with BASIC—PLUS—2. 
However, you can access the information in bytes 9 through 12 in the returned string 
more efficiently in VAX—11 BASIC by using the USEROPEN clause in the OPEN 
statement. 


Examples 


300 A$ = FSP$(1) 
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27.0 FSS$ (BASIC—-PLUS—2 Only) 


Function 


The FSS$ function scans a file name string beginning at a specified position and returns a 
30—character string describing the file name and status. Because file specifications differ from system 
to system, the returned string contains system-specific information. See BASIC on RSX—11M/M-—PLUS 
Systems or BASIC on RSTS/E Systems for more information on the values returned by the FSS$ 
function. 


Format 


str-vbl = FSS§(str-vbl, int-vbl) 


Syntax Rules 
1. Str-vbl names the file name string to be scanned. 


2.  Int-vbl specifies the character position at which scanning starts. 


General Rules 


1. If you specify a floating-point variable for int-vbIl, BASIC truncates it to an integer of the 
default size. 


2. Str-vbl is a 30-character string. See BASIC on RSX—11M/M-—PLUS Systems and BASIC on 
RSTS/E Systems for information on the encoding of str-vbl. 


Note 


VAX—11 BASIC does not support the FSS$ function. However, the DEFAULTNAME 
clause in the OPEN statement supplies default file specification components. 


Examples 


100 ¥$ = FOSS (AS +BZ) 
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Function 


The GETRFA function returns the Record File Address (RFA) of the last record accessed in an RMS file 
open on a specified channel. 


Format 


Syntax Rules 
1. Rfa-vbl is a variable of the RFA data type. 


2. Chnl-exp is the channel number of an open RMS file. You cannot include a pound sign (#) 
in the channel expression. 


3. You must access a record in the file with a GET, FIND, or PUT statement before using the 
GETRFA function, or BASIC signals ‘“No current record’”’ (ERR = 131). 


General Rules 


1. There must be a file open on the specified chni-exp or BASIC signals an error. 


2. You can use the GETRFA function with RMS sequential, relative, indexed, and (except on 
RSTS/E systems) block I/O files. 


3. The RFA value returned by the GETRFA function can be used only for assignments to and 


comparisons with other variabies of the RFA data type. Comparisons are limited to equal to 
(=) and not equal to (<>) relational operations. 


4. RFA values cannot be printed or used for any arithmetic operations. 


Examples 
100 DECLARE RFA R_ARRAY (99) 
| 
500 FOR 1% = 1% TO 100% 
PUT #1 
R-ARRAY(I%) = GETRFA(1) 
NEXT 1% 
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29.0 INSTR 


Function 


The INSTR function searches for a substring within a string. It returns the position of the substring’s 
starting character. 


Format 


int-vbl = INSTR(int-exp, str-exp1, str-exp2) 


Syntax Rules 


None. 


General Rules 


1. The INSTR function searches str-exp7, the main string, for the first occurrence of a 
substring, str-exp2, and returns the position of the substring’s first character. 


2. Int-exp specifies the character position in the main string at which BASIC starts the search. 


3. INSTR returns the character position in the main string at which BASIC finds the substring, 
except in the following situations: 


e If only the substring is null, and if int-exp is less than or equal to zero, INSTR returns a 
value of one. 


® If only the substring is null, and if int-exp is equal to or greater than one and less than or 
equal to the length of the main string, INSTR returns the value of int-exp. 


e If only the substring is null, and if int-exp is greater than the length of the main string, 
INSTR returns the main string’s length plus one. 


e If the substring is not null, and if int-exp is greater than the length of the main string, 
INSTR returns zero. 


e If only the main string is null, INSTR returns zero. 


e If both the main string and the substring are null, INSTR returns one. 


4. If BASIC cannot find the substring, INSTR returns zero. 


5. If int-exp does not equal one, BASIC still counts from the beginning of the main string to 
calculate the starting position of the substring. That is, BASIC counts character positions 
starting at position one, regardless of where you specify the start of the search. For exam- 
ple, if you specify 10 as the start of the search and BASIC finds the substring at position 15, 
INSTR returns the value 15. 


6. If int-exp is less than one, BASIC assumes a starting position of one. 


7. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 
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Note 


VAX-11 BASIC supplies the INSTR = function only for compatibility with 
BASIC—PLUS—2 and BASIC—PLUS. DIGITAL recommends that you use the POS func- 
tion for substring searches. 


Examples 


300 ¥Y = INSTR(1s ALPHAS:s "JKLMN") 
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30.0 INT 


Function 


The INT function returns the floating-point value of the largest whole number less than or equal to a 
specified expression. 


Format 


real-vbl = INT(real-exp) 


Syntax Rules 


None. 


General Rules 


1. If real-exp is negative, BASIC returns the largest whole number less than or equal to 
real-exp. For example, INT(—5.3) is —6. 


2. BASIC expects the argument of the INT function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 


3. This example contrasts the INT and FIX functions: 


10 TEST_NUM = -32,.7 

20 PRINT “INT OF -32.7 15: "5 INT(TEST_NUM) 
30 PRINT "FIX OF -32.7 IS: "3 FIX(TEST_NUM) 
40 END 


RUNNH 


INT OF -32.7 IS: -33 
FIX OF -32,.7 IS: -32 


Examples 


650 RESULT = INT(6.667) 
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31.0 INTEGER 


Function 


The INTEGER function converts a numeric expression or numeric string to a specified or default 
INTEGER data type. 


Format 
[, Lona | 
int-vbl = INTEGER(exp | , BYTE | ) 
, WORD 


Syntax Rules 


1. Exp can be either numeric or string. A string expression can contain the ASCII digits 0 
through 9, a plus sign (+), or a minus sign (—). 


General Rules 


1. BASIC evaluates exp, then converts it to the specified INTEGER size. If you do not specify a 
size, BASIC uses the default INTEGER size. 


2. If exp is a string, BASIC ignores leading and trailing spaces and tabs. 


3. The INTEGER function returns a zero when a string argument contains only spaces and 
tabs, or when it is null. 


Examples 


1006 INPUT "Enter a floating-rPoint number" sF_P 
PRINT INTEGER(F_LP+ WORD? 
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32.0 LEFTS$ 


Function 


The LEFT$ function extracts a specified substring from a string’s left side, leaving the main string 
unchanged. 


Format 


LEFT 


str-vbl = LEFT$ (str-exp, int-exp) 


Syntax Rules 
None. 
General Rules 


1. The LEFT$ function extracts a substring from the left of the specified str-exp and stores it in 
str-vbl. 


Int-exp specifies the number of characters to be extracted from the left side of the str-exp. 
If int-exp is less than one, LEFT$ returns a null string. 


If int-exp is greater than the length of str-exp, LEFT$ returns the entire string. 


wm BS Ww ho 


If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 


Note 


VAX—11 BASIC supplies the LEFT$ function only for compatibility with BASIC—PLUS 
and BASIC—PLUS—2. DIGITAL recommends that you use the SEG$ function for sub- 
string extraction. 


Examples 


410 SUB_STRINGS = LEFT#S(ALPHAS:, 5%) 
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33.0 LEN 
Function 


The LEN function returns an integer value equal to the number of characters in a specified string. 


Format 


int-vbl = LEN(str-exp) 
i 


Syntax Rules 
None. 
General Ruies 
1. — If str-exp is null, LEN returns a value of zero. 


2. The length of str-exp includes leading, trailing, and embedded blanks. Tabs in str-exp are 
treated as a single space. 


3. The value returned by the LEN function is an integer of the default size. 


Examples 


200 LENGTH = LEN(CALPHAS) 
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34.0 LOC (VAX-11 BASIC Only) 


Function 


The LOC function returns a longword integer specifying the virtual address of a simple or subscripted 
variable. For dynamic strings, the LOC function returns the address of the descriptor rather than the 
address of the data. 


Format 


int-vbl = LOC(vbl) 


Syntax Rules 


1. Vb/ can be any local or external, simple or subscripted variable. 


2. VbI cannot be a virtual array element. 
General Rules 


1. The LOC function always returns a LONG value. 


Examples 
100 DECLARE LONG B; A 
200 A = LOC(B) 
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35.0 LOG 


Function 


The LOG function returns the natural logarithm (base “e’’) of a specified number. The LOG function 
is the inverse of the EXP function. 


Format 


| real-vbl = LOG(real-exp) | 


Syntax Rules 
None. 
General Rules 


1. Real-exp must be greater than zero. An attempt to find the logarithm of zero or a negative 
number causes BASIC to signal “Illegal argument in LOG” (ERR=53). 


2. The LOG function uses the mathematical constant ‘‘e’’ as a base. BASIC approximates “‘e’”’ 
to be 2.718281828459045 (double precision). 


3. The LOG function returns the exponent to which ‘‘e’’ must be raised to equal real-exp. 


4. BASIC expects the argument of the LOG function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 


Examples 


10 EXPONENT = LOG(100,.35} 
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36.0 LOG10 


Function 


The LOG10 function returns the common logarithm (base 10) of a specified number. 


Format 


real-vbl = LOG10(real-exp) 


Syntax Rules 
None. 
General Rules 


1. Real-exp must be larger than zero. An attempt to find the logarithm of zero or a negative 
number causes BASIC to signal ‘Illegal argument in LOG” (ERR=53). 


2. The LOG10 function returns the exponent to which 10 must be raised to equal real-exp. 


3. BASIC expects the argument of the LOG10 function to be a real-exp. When the argument is 
a real-exp, BASIC returns a vaiue of the same floating-point size. When the argument is not 
a real-exp, BASIC converts the argument to the default floating-point size and returns a 
value of the default floating-point size. 


Examples 


600 EXP_BASE_10 = LOG10(250) 
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Function 


The MAG function returns a number that equals the absolute value of a specified expression. The 
returned value has the same data type as the expression. 


Format 


Syntax Rules 


None. 


General Rules 


1. The returned value is always greater than or equal to zero. The absolute value of zero is 
zero. The absolute value of a positive number equals that number. The absolute value of a 
negative number equals that number multiplied by minus one. 


2. The MAG function is similar to the ABS function in that it returns the absolute value of a 
number. The ABS function, however, takes a floating-point argument and returns a 
floating-point value. The MAG function takes an argument of any numeric data type and 
returns a value of the same data type as the argument. 


Examples 
100 DECLARE LONG A 
200 PRINT MAG(A) 
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38.0 MAGTAPE 


Function 


The MAGTAPE function permits your program to control unformatted magnetic tape files. 


Format 


Syntax Rules 


1. Int-const is an integer between 1 and 9, inclusive, that specifies the code for the MAGTAPE 
function you want to perform. Function codes are described in Table 23. See BASIC on 
RSX-11M/M-PLUS Systems or BASIC on RSTS/E Systems for more information on mag- 
netic tape function codes. 


2. VAX—11 BASIC supports only function code 3, rewind tape. Table 24 explains how to 
perform other MAGTAPE functions on VAX/VMS Systems. 


3.  Int-vb/l2 is an integer parameter for function codes 4, 5, and 6. 


e Int-vbl2 for function 4 is a value from 1 to 32767, inclusive, that specifies the number of 
records to skip. 


e Int-vb/2 for function 5 is a value from 1 to 32767, inclusive, that specifies the number of 
records to backspace. 


e Int-vbl2 for function 6 specifies the density and/or parity of the magnetic tape drive. See 
BASIC on RSX—11M/M-—PLUS Systems or BASIC on RSTS/E Systems for information on 
setting the density and parity of the magnetic tape drive. 


4. The chnl-exp associated with the magnetic tape must be open. 


Table 23: MAGTAPE Function Codes 


Rewind and take tape off-line 


Write end-of-file (EOF) mark 


— 


Rewind tape 

Advance tape a specified number of records 
Backspace tape a specified number of records 
Set density and parity 

Return status of tape 


Return characteristics of file open on tape (RSTS/E only) 


2 
3 
4 
5 
6 
7 
8 
9 


Rewind when file is closed (RSTS/E only) 
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1. You cannot use the MAGTAPE function with RMS files. 

2. Function codes 8 and 9 are valid only on RSTS/E systems. 

3. If int-const equals 1, 2, 3, 6, or 9, int-vbl1 always equals zero. 
4 


If int-const equals 4, int-vb/7 is an integer of the default size that equals the number of 
records not skipped. 


5. If int-const equals 5, int-vbl7 is an integer of the default size that equals the number of 
records not backspaced. 


6. If int-const equals 7, int-vbl7 is a 16—bit integer that reflects the status of the specified 
magnetic tape. See BASIC on RSX—11M/M-—PLUS Systems or BASIC on RSTS/E Systems for 
information on bit values and meaning. 


7. If int-const equals 9, int-vbI1 is a 16—bit integer that describes the file characteristics of the 
specified magnetic tape. See the RSTS/E Programming Manual for information on bit 
values and meaning. 


8. On RSTS/E systems, the “rewind when file is closed’’ function (9) must appear after the 
OPEN statement and before the CLOSE statement associated with the specified magnetic 
tape. 


Table 24: Performing MAGTAPE Functions in VAX—11 BASIC 


MAGTAPE Function VAX—11 BASIC Actions 


Write EOF 


Close channel | 


Skip records Perform GETs, ignore data until reaching de- 


sired record 


Backspace Rewind tape, perform GETs, ignore data until 


reaching desired record 


Use the DCL MOUNT command qualifiers 
(/DENSITY and /FOREIGN), or the $MOUNT 
system service 


Use the USEROPEN clause in the OPEN state- 
ment to access the RAB$L_STS and _ the 
RAB$L_STV 


Set density 


Status 


Examples 


200 I = MAGTAPE (15032) 
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39.0 MAR (VAX-11 BASIC Only) 


Function 


The MAR function returns the current margin width of a specified channel. 


Format 


MAR 


int-vbl = MAR% (chni-exp) 


Syntax Rules 
None. 
General Rules 


1. The file associated with chn/-exp must be open. You cannot include a pound sign (#) in 
chnl-exp. 


2. If chnl-exp specifies a terminal, the MAR function returns zero if you have not set a margin 
width with the MARGIN statement. If you have set a margin width, the MAR function 
returns that number. 


3. The value returned by the MAR function is an integer of the default size. 
Examples 


200 WIDTH = MAR(O) 
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Function 


The MID$ function extracts a specified substring from the middle of a string, leaving the main string 
unchanged. 


Format 
| (mip | | 
str-vbl = MID$ | (str-exp, int-exp1, int-exp2) 


Syntax Rules 
None. 
General Rules 


1. - The MID$ function extracts a substring from str-exp and stores it in str-vbl. Int-exp1 speci- 
fies the position of the substring’s first character. Int-exp2 specifies the length of the sub- 
string. 


2. If int-exp7 is less than one, BASIC assumes a starting position of one. 
3. If int-exp7 is greater than the length of str-exp, MID$ returns a null string. 


4. If int-exp2 is greater than the length of str-exp, BASIC returns the string that begins at 
int-exp1 and includes all characters remaining in the string. 


5. _ If int-exp2 is less than or equal to zero, MID$ returns a null string. 


6. If you specify a floating-point expression for int-exp7 or int-exp2, BASIC truncates it to an 
integer of the default size. 


Note 


VAX-11 BASIC supplies the MID$ function only for compatibility with BASIC—PLUS 
and BASIC—PLUS—2. DIGITAL recommends that you use the SEG$ function for sub- 
string extraction. 


Examples 


2209 NEWLSTRINGS = MID#(OLD_STRINGS; 3+ 8) 


February 1984 BASIC Reference Manual 335 


NOECHO 


41.0 NOECHO 


Function 


The NOECHO function disables echoing of input on a terminal. 


Format 


int-vbl = NOECHO(chni-exp) 


Syntax Rules 
None. 
General Rules 
1. Chnl-exp must specify a terminal. You cannot include a pound sign (#) in chnl-exp. 


2. If you specify NOECHO, BASIC still accepts characters typed on the terminal as input, but 
the characters do not echo on the terminal. 


3. The NOECHO function is the complement of the ECHO function; that is, NOECHO dis- 
ables the effect of ECHO and vice versa. 


4. NOECHO always returns zero. 


Examples 


300 ¥Y = NOECHO(O) 
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42.0 NUM 


Function 


The NUM function returns the row number of the last data element transferred into an array by a MAT 
1/O statement. 


Format 


| int-vbl = NUM | 


ae 


Syntax Rules 
None. 
General Rules 
1. NUM returns zero if it is invoked before BASIC has executed any MAT |/O statements. 


2. Fora two-dimensional array, NUM returns an integer specifying the row number of the last 
data element transferred into the array. For a one-dimensional array, NUM returns the 
number of elements entered. 


3. The value returned by the NUM function is an integer of the default size. 


Examples 


10 ROW_COUNT = NUM 


BASIC Reference Manual 337 


NUM2 


43.0 NUM2 


Function 


The NUM2 function returns the column number of the last data element transferred into an array by a 
MAT 1/O statement. 


Format 


int-vbl = NUM2 


Syntax Rules 
None. 
General Rules 


1. NUM2 returns zero if it is invoked before BASIC has executed any MAT 1|/O statements or 
if the last array element transferred was in a one-dimensional list. 


2. The NUM2 function returns an integer specifying the column number of the last data 
element transferred into an array. 


3. The value returned by the NUM2 function is an integer of the default size. 


Examples 


100 COLUMN_COUNT = NUM2 
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44.0 NUMS$ 


Function 
The NUM$ function evaluates a numeric expression and returns a string of characters in PRINT 
statement format, with leading and trailing spaces. 


Format 


str-vbl = NUM$(num-exp) 
ee 
Syntax Rules 


None. 


General Rules 


1. If num-exp is positive, the first character in the string expression is a space. If num-exp is 
negative, the first character is a minus sign. 


2. The NUM¢$ function does not include trailing zeros in the returned string. If all digits to the 
right of the decimal point are zeros, NUM$ omits the decimal point as well. 


3. When num-exp has an integer portion of six digits or less (for example, 1234.567), BASIC 
rounds the number to six digits (1234.57). If num-exp has seven decimal digits or more, 
BASIC rounds the number to six digits and prints it in E format. 


4, When num-exp is between 0.1 and 1, BASIC rounds it to six digits. When num-exp is 
smaller than 0.1, BASIC rounds it to six digits and prints it in E format. 


if num-exp is a longword integer, the returned string can have up to 10 digits. 


qa 


6. The last character in the returned string is a space. 


Examples 


660 NUMBERS = NUM$(34.55000/32.4) 
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45.0 NUM1$ 


Function 


The NUM1$ function changes a numeric expression to a numeric character string without leading 
and trailing spaces. 


Format 


str-vbl = NUM1$(num-exp) 


Syntax Rules 
None. 
General Rules 


1. The NUM1$ function returns a string consisting of numeric characters and a decimal point 
that corresponds to the value of num-exp. Leading and trailing spaces are not included in 
the returned string. 


2. The NUM1$ function returns: 
¢ Three digits for BYTE integers 
e Five digits for SINGLE floating-point numbers and WORD integers 
e Ten digits for LONG integers 
e Sixteen digits for DOUBLE floating-point numbers 
e Fifteen digits for GFLOAT floating-point numbers (VAX—11 BASIC only) 
e Thirty-three digits for HFLOAT floating-point numbers (VAX—17 BASIC only) 


3. The NUM1$ function does not produce E notation. 


Examples 


730 NUMBERS = NUMIS$(PI/2) 
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Function 


The ONECHR function allows single-character input (ODT submode) on a specified channel. This 
function must be used in conjunction with the GET statement. 


Format 


int-vbl = ONECHR(chnl-exp) 


Pe 


Syntax Rules 
1. Chnl-exp must refer to an open terminal. You cannot include a pound sign (#) in chnl-exp. 


2. The ONECHR function must be used immediately before the GET statement. 


General Rules 


1. BASIC disables the ONECHR function immediately after a GET statement executes. There- 
fore, your program must invoke the ONCHR function for each single character input you 
want to perform. 


2. Control passes to the program as soon as you enter a character. You do not have to type a 
line terminator. | 


Examples 
100 OPEN "TI:" FOR INPUT AS FILE #1% 
110 ¥% = ONECHR(1%) 
120 GET #1% 
MOVE FROM #1%+ AS = 1% 
PRINT AS 


Note 


VAX—11 BASIC does not support the ONECHR function. To perform this function in 
VAX—11 BASIC, you must use the system service SYS$QIO. 
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47.0 PLACES 


Function 


The PLACE$ function explicitly changes the precision of a numeric string. PLACE$ returns a numeric 
string, truncated or rounded, according to the value of an integer argument you supply. 


Format 


str-vbl = PLACES(str-exp, int-exp) 


Syntax Rules 


1. 


Str-exp specifies the numeric string you want to process. It can contain up to 60 ASCII 
digits and an optional decimal point and leading sign. 


If str-exp consists of more than 60 characters, BASIC signals the error ‘Illegal number’ 
(ERR = 52). . 


Int-exp specifies the numeric precision of str-exp. Table 25 shows examples of rounding 
and truncation and the values of int-exp that produce them. 


General Rules 


1. 
Ze 
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Str-exp is rounded and/or truncated according to the value of int-exp. 
If int-exp is between —60 and 60, rounding and truncation occur as follows: 


e For positive integer expressions, rounding occurs to the right of the decimal place. For 
example, if int-exp is 1, rounding occurs one digit to the right of the decimal place (the 
number is rounded to the nearest tenth). If int-exp is 2, rounding occurs two digits to the 
right of the decimal place (the number is rounded to the nearest hundredth), and so on. 


© |f int-exp is zero, BASIC rounds to the nearest unit. 


e For negative integer expressions, rounding occurs to the left of the decimal point. If 
int-exp is —1, for example, BASIC moves the decimal point one place to the left, then 
rounds to units. If int-exp is —2, rounding occurs two places to the left of the decimal 
point; BASIC moves the decimal point two places to the left, then rounds to tens. 


If int-exp is between 9940 and 10060, truncation occurs: 


e If int-exp is 10000, BASIC truncates the number at the decimal point. 


e |f int-exp is greater than 10000 (10000 plus n) BASIC truncates the numeric string n 
places to the right of the decimal point. For example, if int-exp is 10001 (10000 plus 1), 
BASIC truncates the number starting one place to the right of the decimal point. If int-exp 
is 10002 (10000 plus 2), BASIC truncates the number starting two places to the right of 
the decimal point, and so on. 
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* if int-exp is less than 10000 (10000 minus n), BASIC truncates the numeric string n places 
to the left of the decimal point. For example, if int-exp is 9999 (10000 minus 1), BASIC 
truncates the number starting one place to the left of the decimal point. If int-exp is 9998 
(10000 minus 2), BASIC truncates the number starting two places to the left of the 
decimal point, and so on. 


4. If int-exp is not between —60 and 60 or 9940 and 10060, BASIC returns zero. 


5. If you specify a floating-point expresstion for int-exp, BASIC truncates it to an integer of the 
default size. 


6. Table 25 shows examples of rounding and truncation and the values of int-exp that pro- 
duce them. The number used is 123456.54321. 


Examples 


300 NUMBERS = PLACES(OLD_NUMBER$:+ 10001) 
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Table 25: Rounding and Truncation of 123456.654321 


Value Returned 


Rounded to 100,000s and truncated 1 
Rounded to 10,000s and truncated 12 
Rounded to 1000s and truncated 123 
Rounded to 100s and truncated 1235 
Rounded to 10s and truncated 12346 
Rounded to units and truncated 123457 
Rounded to tenths and truncated 123456.7 


Rounded to hundredths and truncated 123456.65 


Rounded to thousandths and truncated 123456.654 
Rounded to ten-thousandths and truncated 123456.6543 
Rounded to hundred-thousandths and truncated | 123456.65432 
9,995 Truncated to 100,000s 
9,996 Truncated to 10,000s 
9,997 Truncated to 1000s 
9,998 Truncated to 100s 
9,999 Truncated to 10s 
10,000 | Truncated to units 
10,001 Truncated to tenths 
10,002 | Truncated to hundredths 123456.65 
10,003 | Truncated to thousandths 123456.654 
10,004 | Truncated to ten-thousandths 123456.6543 
10,005 | Truncated to hundred-thousandths 123456.65432 
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48.0 POS 


Function 


The POS function searches for a substring within a string and returns the substring’s starting character 
position. 


Format 


int-vbl = POS(str-exp1, str-exp2, int-exp) 
Ue ee ee ee 


Syntax Rules 


None. 


General Rules 


1. The POS function searches str-exp1, the main string, for the first occurrence of str-exp2, the 
substring, and returns the position of the substring’s first character. 


2.  Int-exp specifies the character position in the main string at which BASIC starts the search. 
3. If int-exp is greater than the length of the main string, POS returns zero. 


4. POS always returns the character position in the main string at which BASIC finds the 
substring: 


e If only the substring is null, and if int-exp is less than or equal to zero, POS returns a 
value of one. 


e If only the substring is null, and if int-exp is equal to or greater than one and less than or 
equal to the length of the main string, POS returns the value of int-exp. 


e If only the substring is null and if int-exp is greater than the length of the main string, POS 
returns the main string’s length plus one. 


e If only the main string is null, POS returns zero. 

e If both the main string and the substring are null, POS returns one. 
5. If BASIC cannot find the substring, POS returns zero. 
6. If int-exp is less than one, BASIC assumes a starting position of one. 


7. If int-exp does not equal one, BASIC still counts from the string’s beginning to calculate the 
starting position of the substring. That is, BASIC counts character positions starting at 
position one, regardless of where you specify the start of the search. For example, if you 
specify 10 as the start of the search and BASIC finds the substring at position 15, POS 
returns the value 15. 
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8. If you know that the substring is not near the beginning of the string, specifying a starting 
position greater than one speeds program execution by reducing the number of characters 
BASIC must search. 


9. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 


Examples 


400 Y = POS(ALPHASs "JKLMN"> 1) 
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49.0 PROD$ 


Function 


The PROD$ function returns a numeric string that is the product of two numeric strings. The precision 
of the returned numeric string depends on the value of an integer argument. 


Format 


| str-vbl = PROD&§(str-exp1, str-exp2, int-exp) | 
Lc a PP Ee Ne ee 


Syntax Rules 


1. 


Str-exp1 and str-exp2 specify the numeric strings you want to process. They can contain up 
to 60 ASCI! digits and an optional decimal! point and leading sign. 


If str-exp consists of more than 60 characters, BASIC signals the error ‘Illegal number’ 
(ERR=52). 


Int-exp specifies the numeric precision of str-exp. Table 25 shows examples of rounding 
and truncation and the values of int-exp that produce them. 


General Rules 


1. 
2 


Str-exp is rounded and/or truncated according to the value of int-exp. 


lf int-exp is between —60 and 60, rounding and truncation occur as follows: 


e For positive integer expressions, rounding occurs to the right of the decimal place. For 
example, if int-exp is 1, rounding occurs one digit to the right of the decimal place (the 
number is rounded to the nearest tenth). If int-exp is 2, rounding occurs two digits to the 
right of the decimal place (the number is rounded to the nearest hundredth), and so on. 


e If int-exp is zero, BASIC rounds to the nearest unit. 


© For negative integer expressions, rounding occurs to the left of the decimal point. If 
int-exp is —1, for example, BASIC moves the decimal point one place to the left, then 
rounds to units. If int-exp is —2, rounding occurs two places to the left of the decimal 
point; BASIC moves the decimal point two places to the left, then rounds to tens. 


If int-exp is between 9940 and 10060, truncation occurs: 


e If int-exp is 10000, BASIC truncates the number at the decimal point. 


e If int-exp is greater than 10000 (10000 plus n), BASIC truncates the numeric string n 
places to the right of the decimal point. For example, if int-exp is 10001 (10000 plus 1), 
BASIC truncates the number starting one place to the right of the decimal point. If int-exp 
is 10002 (10000 plus 2), BASIC truncates the number starting two places to the right of 
the decimal point, and so on. 


(continued on next page) 
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e If int-exp is less than 10000 (10000 minus n), BASIC truncates the numeric string n places 
to the left of the decimal point. For example, if int-exp is 9999 (10000 minus 1), BASIC 
truncates the number starting one place to the left of the decimal point. If int-exp is 9998 
(10000 minus 2), BASIC truncates the number starting two places to the left of the 
decimal point, and so on. 


4, If int-exp is not between —60 and 60 or 9940 and 10060, BASIC returns zero. 


5. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 


6. Table 25 shows examples of rounding and truncation and the values of int-exp that pro- 
duce them. The number used is 123456.654321. 


Examples 


300 PRODUCTS = PRODS("88793", 2%, 0) 
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50.0 QUO$ 


Function 


The QUO$ function returns a numeric string that is the quotient of two numeric strings. The precision 
of the returned numeric string depends on the value of an integer argument. 


Format 


str-vbl = QUOS(str-exp1, str-exp2, int-exp) 
Se a ac a are ee AE | 


Syntax Rules 


1. 


Str-exp1 and str-exp2 specify the numeric strings you want to process. They can contain up 
to 60 ASCII digits and an optional decimal point and leading sign. 


If str-exp consists of more than 60 characters, BASIC signals the error “Illegal number’ 
(ERR = 52). 


Int-exp specifies the numeric precision of str-exp. Table 25 shows examples of rounding 
and truncation and the values of int-exp that produce them. 


General Rules 


1. 
2: 


Str-exp is rounded and/or truncated according to the value of int-exp. 


If int-exp is between —60 and 60, rounding and truncation occur as follows: 


e For positive integer expressions, rounding occurs to the right of the decimal place. For 
example, if int-exp is 1, rounding occurs one digit to the right of the decimal place (the 
number is rounded to the nearest tenth). If int-exp is 2, rounding occurs two digits to the 
right of the decimal place (the number is rounded to the nearest hundredth), and so on. 


e If int-exp is zero, BASIC rounds to the nearest unit. 


e For negative integer expressions, rounding occurs to the left of the decimal point. If 
int-exp is —1, for example, BASIC moves the decimal point one place to the left, then 
rounds to units. If int-exp is —2, rounding occurs two places to the left of the decimal 
point; BASIC moves the decimal point two places to the left, then rounds to tens. 


If int-exp is between 9940 and 10060, truncation occurs: 


e If int-exp is 10000, BASIC truncates the number at the decimal point. 


e If int-exp is greater than 10000 (10000 plus n), BASIC truncates the numeric string n 
places to the right of the decimal point. For example, if int-exp is 10001 (10000 plus 1), 
BASIC truncates the number starting one place to the right of the decimal point. If int-exp 
is 10002 (10000 plus 2), BASIC truncates the number starting two places to the right of 
the decimal point, and so on. 


(continued on next page) 
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Examples 


200 


e If int-exp is less than 10000 (10000 minus n), BASIC truncates the numeric string n places 
to the left of the decimal point. For example, if int-exp is 9999 (10000 minus 1), BASIC 
truncates the number starting one place to the left of the decimal point. If int-exp is 9998 
(10000 minus 2), BASIC truncates the number starting two places to the left of the 
decimal point, and so on. 


If int-exp is not between —60 and 60 or 9940 and 10060, BASIC returns zero. 


If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 


Table 25 shows examples of rounding and truncation and the values of int-exp that pro- 
duce them. The number used is 123456.654321. 


QUOTIENTS = QUOS$("453.221"5 "30", 10000) 
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51.0 RADS 


Function 


The RAD$ function converts a specified integer to a 3—character string in Radix—50 format. 


Format 


str-vbl = RADS&(int-vbl) 


Syntax Rules 


None. 


General Rules 


1. The RAD$ function converts int-vb/ to a 3—character string in Radix—50 format and stores it 
in str-vb]. Radix—50 format allows you to store three characters of data as a 2—byte integer. 


2. See Appendix C in BASIC on RSX-11M/M-—PLUS Systems or BASIC on RSTS/E Systems for 
information on the Radix—50 character set and ASCII/Radix—50 equivalents. 


3. VAX-11 BASIC supports the RAD$ function, but not its complement, the FSS$ function. 
DIGITAL recommends that you use Run-Time Library routines for Radix—50 operations. 


4. If you specify a floating-point variable for int-vb!, BASIC truncates it to an integer of the 
default size. 


Examples 


RP Pras 


i606 RADIXS = RADS(555) 
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52.0 RCTRLC 


Function 
The RCTRLC function disables CTRL/C trapping. 


Format 


| int-vbl = RCTRLC | 


Syntax Rules 
None. 
General Rules 


1. After BASIC executes the RCTRLC function, a CTRL/C typed at the terminal returns you to 
command level (BASIC or monitor). 


2. RCTRLC always returns a zero. 


. 


Examples 


200 Y = RCTRLC 
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Function 
The RCTRLO function cancels the effect of a CTRL/O typed on a specified channel. 


Format 


int-vb! = RCTRLO (chni-exp) 


Syntax Rules 


None. 


Generai Rules 
1. Chnl-exp must refer to a terminal. 


2. RCTRLO has no effect if the specified channel is open to a device that does not use the 
CTRL/O convention. 


3. If you type a CTRL/O to cancel terminal output, nothing is printed on the specified termi- 
nal unti! your program executes the RCTRLO or until you type another CTRL/O, at which 
time normal terminal output resumes. 


4. The RCTRLO function always returns a zero. 


Examples 
10 PRINT "A" FOR I% = 1% TO 100% 
YZ = ROTRLOCGZ) 


PRINT "Normal outrut is resumed” 
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54.0 REAL 


Function 


The REAL function converts a numeric expression or numeric string to a specified or default floating- 
point data type. 


Format 


, SINGLE 
real-vbl = REAL(exp | , DOUBLE | ) 


, GFLOAT (VAX-117 only) 
, HELOAT (VAX-17 only) 


Syntax Rules 


1. Exp can be either a numeric expression or a numeric string. If a numeric string, exp can 
contain the ASCII digits 0 through 9, uppercase E, and an optional decimal point and 
leading sign. 


General Rules 


1. BASIC evaluates exp, then converts it to the specified REAL size. If you do not specify a 
size, BASIC uses the default REAL size. 


2. BASIC ignores leading and trailing spaces and tabs if exp is a string. 


3. The REAL function returns a zero when a string argument contains only spaces and tabs, or 
when the argument is null. 


Examples 


100 INPUT "Enter a number” Ss INTONUM 
PRINT REALCINT_NUM; DOUBLE? 
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Function 


The RECOUNT function returns the number of characters transferred by the last input operation. 


Format 


| int-vb! = RECOUNT | 


Syntax Rules 


None. 
Genera! Rules 


1. The RECOUNT value is set by every input operation on any channel, including channel 
zero. 


e After an input operation from your terminal, RECOUNT contains the number of charac- 
ters (bytes), including line terminators, transferred. 


e After accessing a file record, RECOUNT contains the number of characters in the record. 


2. Because RECOUNT is reset by every input operation on any channel, use the RECOUNT 
function to copy the RECOUNT value to a different storage location before executing 
another input operation. 


3. If an error occurs during an input operation, the value of RECOUNT is undefined. 


4. RECOUNT is unreliable after a CTRL/C interrupt because the CTRL/C trap may have 
occurred before BASIC set the value for RECOUNT. 


5. The RECOUNT function returns a LONG value in VAX—11 BASIC and a WORD value in 
BASIC—PLUS-2. 


Examples 


200 CHARACTER_COUNT = RECOUNT 
PRINT CHARACTER_COUNT:’ characters received’ 
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56.0 RIGHTS 


Function 


The RIGHT$ function extracts a substring from a string’s right side, leaving the main string 
unchanged. 


Format 


RIGHT 


str-vbl = RIGHTS (str-exp, int-exp) 


Syntax Rules 
None. 
General Rules 


1. The RIGHT$ function extracts a substring from str-exp and stores the substring in str-vbl. 
The substring begins with the character in the position specified by int-exp and ends with 
the rightmost character in the string. 


2. If int-exp is less than or equal to zero, RIGHT$ returns the entire string. 
3. If int-exp is greater than the length of str-exp, RIGHT$ returns a null string. 


4. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 


Examples 


600 NEW_STRINGS = RIGHT#(ALPHAS$: 21) 


Note 


VAX—11 BASIC includes the RIGHT$ function only for compatibility with BASIC—PLUS 
and BASIC—PLUS—2. DIGITAL recommends using the SEG$ function for substring 
extraction. 
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57.0 RND 


Functions 


The RND function returns a random number greater than or equal to zero and less than one. 


Format 


real-vbl = RND 


Syntax Rules 


None. 


General Rules 


1. The RND function returns a pseudorandom number if not preceded by a RANDOMIZE 
statement; that is, each time a program runs, BASIC generates the same random number or 
series of random numbers. 


2. If the RND function is preceded by a RANDOMIZE statement, BASIC generates a different 
random number or series of numbers each time a program executes. 


3. In BASIC—PLUS-—2, the RND function returns a floating-point value of the default size. in 
VAX—11 BASIC, RND always returns a single-precision value. 


Examples 


990 R_NUM = RND 
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58.0 SEGS$ 


Function 


The SEG$ function extracts a substring from a main string, leaving the original string unchanged. 


Format 


str-vbl = SEG&§(str-exp, int-exp1, int-exp2) 


General Rules 


1. BASIC extracts the substring from str-exp, the main string, and stores the substring in 
str-vbIl. The substring begins with the character in the position’ specified by int-exp7 and 
ends with the character in the position specified by int-exp2. 


2. If int-exp7 is less than one, BASIC assumes a value of one. 


3. If int-exp7 is greater than int-exp2 or the length of str-exp, the SEG$ function returns a null 
string. 


4. If int-exp1 equals int-exp2, the SEG$ function returns the character at the position specified 
by int-exp7. 


5. Unless int-exp2 is greater than the length of str-exp, the length of the returned substring 
equals int-exp2 minus int-exp7 plus one. If int-exp2 is greater than the length of str-exp, the 
SEG$ function returns all characters from the position specified by int-exp1 to the end of 
SU-eXxp. 


6. If you specify a floating-point expression for int-exp7 or int-exp2, BASIC truncates it to an 
integer of the default size. 


Examples 


300 CENTERS = SEGS(ALPHAS: 15% 20) 
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Function 


The SGN function determines whether a numeric expression is positive, negative, or zero. It returns a 
one if the expression is positive, a minus one if the expression is negative, and zero if the expression 
is zero. 


Format 
SS el 
int-vbl = SGN(real-exp) 


Syntax Rules 


None. 


General Rules 
1. If real-exp does not equal zero, SGN returns ABS(real-exp) /real-exp. 
2. If real-exp equals zero, SGN returns zero. 
3. SGN returns an integer of the default size. 

Examples 


750 SIGN = SGN(-4535 /6-3000) 
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60.0 SIN 


Function 


The SIN function returns the sine, in radians, of an angle. 


Format 


real-vbl = SIN(real-exp) 


Syntax Rules 
None. 
General Rules 
1. The returned value is between minus one and one. 


2. BASIC expects the argument of the ABS function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 


Examples 


100 S1_ANGLE = SIN(PI/2) 
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61.0 SPACES 


Function 


The SPACE$ function creates a string containing a specified number of spaces. 


Format 


str-vbl = SPACES(int-exp) 


Syntax Rules 
None. 
Generai Rules 
1. Int-exp specifies the number of spaces in the returned string. 
2.. BASIC treates an int-exp less than zero as zero. 


3. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 


Examples 


B80 FILLERS = SPACE$(32) 
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62.0 SQR 


Function 


The SQR function returns the square root of a positive number. 


Format 


SQRT 


real-vbl = | SQR_} (real-exp) 


Syntax Rules 


None. 


General Rules 


1. VAX—11 BASIC signals the error ‘‘Imaginary square roots’ (ERR=54) and program execu- 
tion stops when real-exp is negative. 


2. BASIC—PLUS—2 returns the warning message ‘“%Ilmaginary square roots” and the square 
root of the absolute value of the expression when real-exp is negative. The program does 
not stop executing. 


3. BASIC assumes that the argument of the SQR function is a real-exp. When the argument is 
a real-exp, BASIC returns a value of the same floating-point size. When the argument is not 
a real-exp, BASIC returns a value of the default floating-point size. 


Examples 


425 ROOT = SOR(35*37) 
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63.0 STATUS 


Function 


The STATUS function returns an integer value containing information about the last opened channel. 
Your program can test each bit to determine the status of the channel. 


Format 


| int-voll = STATUS | 


a a a ee a ee eee ITE | 


Syntax Rules 


None. 


General Rules 


1. 


ho 


aw 


The STATUS function returns a WORD integer in BASIC—PLUS—2 and a LONG integer in 
VAX—11 BASIC. 


The value returned by the STATUS function is undefined until BASIC executes an OPEN 
statement. 


The STATUS value is set by every input operation on any channel. Therefore, the STATUS 
value should be copied to a different storage location before your program executes 
another input operation. 


The syntax for STATUS is the same for VAX—11, RSTS/E, and RSX-11M/M-—PLUS systems. 
However, the returned information is different on every system. 


PAC Ae wt 


M/M-—PLUS systems dispiays a 


e The RMS—11 primary status field (STS) or the RMS secondary status field (STV). See the 
RMS—11 MACRO User’s Guide for more information. 


e The device characteristics after an RMS—11 OPEN file operation (set by the DEV field of 
the FAB). See the RMS—11 MACRO User’s Guide for more information. 


¢ The Directive Status Word ($DSW) and its corresponding error code, in the event of a 
directive error. See the RSX—11M/M-—PLUS Mini Reference for the error codes. 


@ The STATUS field of a QIO. See the RSX—11M/M-—PLUS I/O Drivers Reference Manual 
for more information. 


e The first word of a GETLUN directive describing device characteristics. See the 
RSX—11M/M-—PLUS Executive Reference Manual. 


See BASIC on RSX—11M/M-PLUS Systems for information on STATUS values set for an 
OPEN file operation with no errors. 
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Depending on the error, the STATUS function on RSTS/E systems displays a value repre- 
senting one of the following: 


¢ The RMS—11 primary status field (STS) or the RMS secondary status field (STV). See the 
RMS—11 MACRO User’s Guide for more information. 


e The device characteristics after an RMS—11 OPEN file operation (set by the DEV field of 
the FAB). See the RMS—11 MACRO User’s Guide for more information. 


For OPEN operations where no errors occur, the status word describes the device charac- 
teristics of the FIRQB and FQFLAG field. The first 7 bits describe the device, and bits 7 
through 15 describe characteristics of the OPEN statement. See the BASIC—PLUS Language 
Manual and the RSTS/E System Directives Manual for more information on STATUS 
values. 


In VAX—11 BASIC, if an error occurs during an input operation, the value of STATUS is 
undefined. When no error occurs, the six low-order bits of the returned value contain 
information about the type of device accessed by the last input operation. Table 26 lists 
STATUS bits set by VAX—117 BASIC. 


Table 26: VAX—11 BASIC STATUS Bits 


Bit Set Device Type 


Record-oriented device 


Carriage-control device 
Terminal 


Directory device 


Single directory device 


Sequential block-oriented device (magtape) 


Examples 


150 Y%Z = STATUS 
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64.0 


Function 


The STR$ function changes a numeric expression to a numeric character string without leading and 
trailing spaces. 


Format 
| str-vbl = STRS$(num-exp) | 


Syntax Rules 


None. 


General Rules 
1. If num-exp is negative, the first character in the returned string is a minus sign. 


2. Like the NUM$ function, the STR$ function produces E notation. Unlike the NUM$ func- 
tion, the STR$ function does not return leading or trailing spaces. 


3. Like the NUM1$ function, the STR$ function does not return leading or trailing spaces. 
Unlike the NUM1$ function, the STR$ function produces E notation. 


4. When you print a number whose integer portion is six digits or less (for example, 
1234.567), BASIC rounds the number to six digits (1234.57). If a number has seven integer 
digits or more, BASIC rounds the number to six digits and prints it in E format. 


5. When you print a number with magnitude between 0.1 and 1, BASIC rounds it to six digits. 
When you print a number with magnitude smaiier than 0.1, BASIC rounds it to six digits 
and prints it in E format. 


Examples 


B00 2$ = STR#(65) 
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65.0 STRINGS 


Function 


The STRING$ function creates a string containing a specified number of identical characters. 


Format 


str-vbl = STRINGS§(int-exp1, int-exp2) 


Syntax Rules 


None. 


General Rules 


i 


qn 


Examples 


340 


366 


Int-exp1 specifies the character string’s length. VAX—17 BASIC signals the error ‘String too 
long’’ (ERR=227) if int-exp? is greater than 65535. BASIC—PLUS—2 signals the error 
“Integer error’ (ERR=51) if int-exp is greater than 32767. 


If int-exp1 is less than or equal to zero, BASIC treats it as zero. 


Int-exp2 is the decimal ASCII value of the character that makes up the string. This value is 
treated modulo 256. 


BASIC treats all arguments as unsigned 8—bit integers. Negative numbers are treated as the 
two’s complement (for example, —1 is treated as 255). 


lf either int-exp? or int-exp2 is a floating-point expression, BASIC truncates it to an integer 


of the default size. 


A-STRINGS = STRING$(i0; 65) 
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66.0 SUMS 


Function 


The SUM$ function returns a string whose value is the sum of two numeric strings. 


Format 


str-vb] = SUM&(str-exp1, str-exp2) 


Syntax Rules 


1. 


Str-exp1 and str-exp2 specify the numeric strings you want to process. They can contain up 
to 54 ASCII digits and an optional decimal point and leading sign. 


General Rules 


im 
2: 


6. 


Examples 


600 


BASIC adds str-exp2 to str-exp1 and stores the result in str-vbl. 


If str-exp71 and str-exp2 are integers, str-vb! takes the precision of the larger string unless 
trailing zeros generate that precision. 


If str-exp? and str-exp2 are decimal fractions, str-vb/ takes the precision of the more precise 
fraction unless trailing zeros generate that precision. 


SUM$ omits trailing zeros to the right of the decimal point. 

The sum of two floating-point numbers takes precision as follows: 

e The sum of the integer parts takes the precision of the larger part. 

e The sum of the decimal fraction part takes the precision of the more precise part. 


SUMS$ truncates leading and trailing zeros. 


SIGMAS = SUM$("234.444"5 AS) 
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67.0 SWAP% 


Function 


The SWAP% function transposes a WORD integer’s bytes. 


Format 


int-vbl = SWAP®*%(int-exp) 


Syntax Rules 


1. SWAP% is a WORD function. BASIC evaluates int-exp and converts it to the WORD data 
type, if necessary. 


General Rules 


1. BASIC transposes the bytes of int-exp and returns a WORD integer. 
Examples 


300 $25 = SWAPZ(3) 
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Function 


The SYS function lets you perform special |/O functions, establish special characteristics for a job, set 
terminal characteristics, and cause the monitor to execute special operations. 


Format 


| str-vbl = SYS(str-exp) | 


Syntax Rules 


1.  Str-exp is a RSTS/E SYS call code. See the RSTS/E Programming Language manual for a 
complete list of SYS call codes and their meanings. 


General Rules 


1. Because SYS calls request that the RSTS/E monitor perform an operation, often the function 
performed has no counterpart on other host systems. However, for compatibility with 
RSTSfE BASIC—PLUS, VAX-—11 BASIC supports a subset of SYS calls. Table 27 lists the 
VAX—11 BASIC subset of RSTS/E SYS calls. 


Table 27: VAX—11 BASIC Subset of RSTS/E SYS Calls 


Cancel CTRL/O 


Not implemented 


Enable echo 


Disable echo 
Not implemenied 


Exit with no prompt 


Call File Processor 
Get core common; can be used only between BASIC images 


Put core common; can be used only between BASIC images 


Oo ON DBD Ww SF W KN 


Exit and clear program 


Reserved 


_ 
fon] 


— 
— 


Cancel type ahead 


—_ 
NO 


Not implemented 


Reserved 


_" 
Ww 


— 
a 


Not implemented 
(continued on next page) 
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Table 27: VAX—11 BASIC Subset of RSTS/E SYS Calls (Cont.) 


These FIP calis (and only these) are aiso supported: 


Terminate file name string scan 

Set priority (can set only priority; requires ALTPRI privilege) 
Begin file name string scan 

Enable CTRL/C trap 

Get error message (VAX—11 BASIC error message) 

Assign a device 

Deassign a device 

Deassign all devices 


Send /receive message (requires SYSNAM privilege) 


Send/receive message (cannot get job number, privileges, 
or receive selection; cannot use DECnet; requires PRMMBX 
privilege) 


Examples 

100 OPEN User_keyboard# AS FILE #1 

200 Tmp$ = SYS(CHR$(1i1)) ! Cancel any typeahead from user 
300 LINUT ‘Enter the first line of text’:sUser_input$ 
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69.0 TAB 


Function 


When used with the PRINT statement, the TAB function moves the cursor or print mechanism right to 
a specified column. 


Format 


str-vbl = TAB(int-exp) 


fi ee 


Syntax Rules 


1. Int-exp specifies the column number of the cursor or print mechanism. 
General Rules 
1. You cannot TAB beyond the current MARGIN restriction. 
The leftmost column position is zero. 
If int-exp is less than the current cursor position, the TAB function has no effect. 


Z 
3 
4. The TAB function can move the cursor or print mechanism only from the left to the right. 
5. You can use more than one TAB function in the same PRINT statement. 

6 


Use semicolons to separate multiple TAB functions in a single statement. If you use com- 
mas, BASIC moves to the next print zone before executing the TAB function. 


7. The TAB function is valid only for terminals. 
8. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 
Examples 
200 PRINT AS$TAB(15) §3B$3TAB(30) §"HELLO" 


BASIC Reference Manual 371 


TAN 


70.0 TAN 


Function 


The TAN function returns the tangent, in radians, of an angle. 


Format 


real-vbl = TAN(real-exp) 


Syntax Rules 


None. 


General Rules 


1. BASIC expects the argument of the ABS function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 

Examples 


390 X = TAN(2*PI) 
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Function 


The TIME function returns the time of day (in seconds) as a floating-point number. On VAX—117 and 
RSTS/E systems the TIME function can also return CPU time and device connect time. 


Format 


Syntax Rules 
None. 
General Rules 
1. The value returned by the TIME function depends on the value of int-exp. 


2. If int-exp equals 0, TIME returns the number of seconds since midnight. 


3. BASIC—PLUS—2 on RSX—11M/M-—PLUS systems accepts only an argument of zero. All 
other arguments to the TIME function are undefined and cause BASIC to signal ‘‘Not 
implemented” (ERR = 250). 


4. VAX-11 BASIC and BASIC-PLUS—2 on RSTS/E systems also accept arguments from 1 
through 4 and return values as shown in Table 28. All other arguments to the TIME 


function are undefined and cause BASIC to signal ‘‘Not implemented’’ (ERR= 250). 


5. tn BASIC—PLUS—2, the TIME function returns a fioating-point value of the default size. In 
VAX—11 BASIC, TIME always returns a single-precision value. 


6. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 
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Table 28: TIME Function Values 


Argument 
Value: 


Examples 


150 


374 


VAX—11 BASIC 
Returns: 


The current job’s CPU time in tenths 
of a second 


The current job’s connect time in 
minutes 


Zero 


Zero 


PRINT TIME(0) 
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BASIC-PLUS—2 on 
RSTS/E Systems Returns: 


The current job’s CPU time in tenths 
of a second 


The current job’s connect time in 
minutes 


Kilo-core ticks 


Device time in minutes 


TIMES 


Function 


The TIME$ function returns a string displaying the time of the day. 


fiend aye \ 
(iMt-Exp) 


Syntax Rules 


None. 


General Rules 
1. If int-exp equals zero, TIME$ returns the current time of day. 
2. Int-exp is the number of minutes before midnight. Str-vb/ is the time of day. 
3. The value of int-exp must be in the range 0 to 1440, inclusive, or BASIC signals an error. 
4 


In VAX—17 BASIC the TIME$ function uses a 12—hour, AM/PM clock. Before 12:00 noon, 
TIMES returns HH:MM AM, and after 12:00 noon, HH:MM PM. 


5. In BASIC~PLUS—2 the TIME$ function uses either an AM/PM or a 24-hour clock. The 
clock type is an installation option. 


6. On RSTS/E systems only, the clock type can also be set by the system manager at system 
start-up time. 


7. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 


Examples 


200 CURRENT.TIMES = TIME$(0) 
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73.0 TRM$ 


Function 


The TRM$ function removes all trailing blanks and tabs from a specified string. 


Format 


str-vbl = TRM§(str-exp) 


Syntax Rules 


None. 


General Rules 


1. The returned str-vb/ is the same as str-exp with all the trailing blanks and tabs removed. 


Examples 


600 NEW_STRINGS = TRM$(OLD_STRINGS$) 
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74.0 VAL 


Function 


The VAL function converts a numeric string to a floating-point value. 


Format 
real-vbl = VAL(str-exp) 


Syntax Rules 


1. Str-exp can contain the ASCII digits 0 through 9, uppercase E, and an optional decimal 
point and leading sign. 


2. BASIC ignores leading, trailing, and embedded spaces and tabs. 


General Rules 

1. If str-exp is null, or contains only spaces and tabs, VAL returns a zero. 

2. The value returned by the VAL function is of the default floating-point size. 
Examples 


100 REAL_NUM = VAL("990,32") 
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75.0 VAL% 


Function 


The VAL% function converts a numeric string to an integer. 


Format 


int-vbl = VAL%(str-exp) 


Syntax Rules 
1. Str-exp can contain the ASCII digits 0 through 9 and an optional leading sign. 
2. BASIC ignores leading, trailing, and embedded spaces and tabs. 


General Rules 

1. If str-exp is null or contains only spaces and tabs, VAL% returns a value of zero. 

2. The value returned by the VAL% function is an integer of the default size. 

3. If str-exp contains a decimal point, BASIC signals the error ‘Illegal number’ (ERR = 52). 
Examples 


100 A = VALZ("999") 
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76.0 XLATE 


Function 


The XLATE function translates one string to another by referencing a table string you supply. 


Format 


Syntax Rules 


1.  Str-exp7 is the input string. Str-exp2 is the table string, and str-vb/ is the returned string. 


General Rules 


1. Str-exp2 can contain up to 256 ASCII characters, numbered from 0 to 255; the position of 
each character in the string corresponds to an ASCII value. Because zero is a valid ASCII 
value (null), the first position in the table string is position zero. 


2. XLATE scans str-exp? character by character, from left to right. It finds the ASCII value n of 
the first character in str-exp? and extracts the character it finds at position n in str-exp2. 
XLATE then appends the character from str-exp2 to str-vb]. XLATE continues this process, 
character by character, until the end of str-exp7 is reached. 


3. The output string may be smaller than the input string. 


e XLATE does not translate nulls. If the character at position n in str-exp2 is a null, XLATE 
does not append that character to str-vbl. 


e if the ASCii vaiue of the input character is outside the range of positions in str-exp2, 
XLATE does not append any character to str-vbl. 


Examples 


100 OUTPUTS = XLATECINPUTS+s TABLES) 
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PART VI 
BASIC-PLUS-2 


Debugger Commands 


Note 


This section describes BASIC—PLUS—2 debugger commands. See BASIC on VAX/VMS 
Systems for information on the VAX—11 Symbolic Debugger. 


BASIC—PLUS—2 debugger commands help you locate run-time errors and debug program modules 
interactively in the BASIC environment or from monitor level. To use debugger commands, you must 
compile or run at least one program module using the /DEBUG qualifier. 


When you run a task-built program, execution stops at the first line number of the first module 
compiled with the /DEBUG qualifier and control passes to the debugger. When you run a program in 
the BASIC environment, control passes to the debugger when the first line number of the program 
executed with the RUN/DEBUG command is encountered or when the first line number of an object 


module compiled with the /DEBUG qualifier and loaded with the LOAD command is encountered. 


When control passes to the BASiIC-PLUS—2 debugger, an identifying message and prompt are 
displayed: 


DEBUG: module-name 


Module-name is the name of the first program module encountered that was compiled with the 
/DEBUG qualifier or executed with the RUN/DEBUG command. The pound sign (#) prompt signals 
you to enter debugger commands. For example: 

#BREAK 300 QED 

#TRACE @ 

#CONTINUE GE 
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In the example on the previous page, the BREAK command will cause execution to stop at the first 
statement on line 300; the TRACE command will cause the line numbers and statement numbers to 
be displayed as they execute. The CONTINUE command causes the program module to execute until 
line 300; input, output, and the processing proceeds as usual until the breakpoint is reached. When 
the BREAK command has successfully executed, the debugger displays a message identifying your 
current position in the program module and prompts for another debugger command. For example: 


at line 100 statement 1 
at line 100 statement 2 
at line 100 statement 3 
at line 200 statement 1 
at line 200 statement 2 


BREAK at line 300 statement 1 DEBTST 


The identifying message names the debugger command that stopped program execution (BREAK), the 
line number and statement where execution stopped, and the name of the currently executing mod- 
ule (DEBTST in the above example). If the main program is executing, no module name is displayed. 
The # prompt signals you to enter more debugger commands. 


Use the EXIT command to exit from the debugger and end program execution. 


When you compile a program with the /DEBUG qualifier, BASIC links the debugger program module 
from the BASIC-PLUS—2 OTS to your program. This increases the size of your task by at least 4K 
bytes. When you task-build the program, the debugger records are included in the executable task 
image. When you run the executable image, BASIC-PLUS—2 accesses these records and you can use 
the debugger commands described in the following sections. 


No debugger records are generated for program modules not compiled with the /DEBUG qualifier. 
Thus, you cannot access information, trace module execution, or establish breakpoints in modules 
not compiled with the /DEBUG qualifier. You can, however, use debugger commands to access 
information about the entire task if you compile at least one program module with the /DEBUG 
qualifier. 


After you have debugged your module and changed the source code where necessary, compile the 
module without the /DEBUG qualifier to reduce memory requirements. 


Debugger commands are described on the following pages. All debugger commands except BREAK 
ON can be abbreviated to three letters. 


For an example of a complete debugging session and more information on using the BASIC—PLUS—2 
debugger, see BASIC on RSTS/E Systems or BASIC on RSX—-11M/M-—PLUS Systems. 
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a 2) fe. 
1.0 BREAK (BASIC-PLUS—2) 
Function 


The BREAK command lets you stop program execution at program line numbers, particular state- 
ments, or at the beginning of CALL statements, user-defined functions, and FOR, UNTIL, and WHILE 
loops. The program stops before executing the specified breakpoint. 


Format 


ee eee 
BREAK ON block 


[ ON ] stmnt-break.,... 


CALL 
DEF 
LOOP 


stmnt-break: lin-num [ .stmnt-num ] [ ;mod-nam ] 


Syntax Rules 


1. The BREAK command with no parameters sets a breakpoint at each line number. The 
program stops at each line number before executing any statements on the line. 


2. Block specifies a block statement. The ON keyword is required. You can specify only one 
block statement in a BREAK ON statement: : 


e BREAK ON CALL stops execution each time BASIC executes a CALL statement to a 
subprogram. The program stops before any statements in the subprogram execute. If you 
are executing a task-built program, both the calling and the called program must be 
compiled with the /DEBUG qualifier or the BREAK ON CALL command has no effect. If 
you are executing a program in the BASIC environment, the called program must be 
compiled with the /DEBUG qualifier. 


e BREAK ON DEF stops execution each time BASIC encounters a user-defined function in a 
module compiled with the /DEBUG qualifier. The statement stops before any statements 
in the function execute. 


e BREAK ON LOOP stops execution each time BASIC encounters a FOR, WHILE, or 
UNTIL statement or modifier. The program stops each time the program loops back to 
the loop statement. The program stops after the loop is initialized or incremented, but 
before any statements in the loop execute. 
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3. Stmnt-break specifies a particular line number or statement where execution is to stop. 
e Lin-num specifies a program line. 


e Stat-num specifies a particular statement associated with lin-num. The period (.) is re- 
quired and must immediately follow the line number. BASIC signals an error if you 
include a space between /in-num and stat-num. The cross-reference listing file lists state- 
ments on multi-statement lines by number. 


¢ Mod-nam specifies that the preceding breakpoint is a breakpoint only in the named 
program module. The semicolon (;) is required. 


e You can specify a maximum of 10 stmnt-break breakpoints. If you specify more than 10 
breakpoints, BASIC signals the error, ‘‘No room’’. 


General Rules 


1. If you specify a stmnt-break or block that does not exist, no break occurs, BASIC does not 
signal an error or warning, and the program executes normally. 


2. To disable program breakpoints, use the UNBREAK command. 
Examples 


#BREAK 30.2, S003PROGB; 2000.35PROGC 
#BREAK ON CALL 
#CON 


BREAK at line 30 statement 2 


# 
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CONTINUE 


9N CONTINIIE 
Gir WIE — 


Function 


The CONTINUE command continues program execution. 


Format 


CONTINUE 


Syntax Rules 


None 


General Rules 


1. When you have finished entering debugger commands, type CONTINUE to resume pro- 
gram execution. 


Examples 


#BREAK ON LOOP 
#CON 
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3.0 CORE (BASIC-PLUS-2) 


Function 


The CORE command returns the number of words currently allocated in memory for your entire task. 
Use the CORE command in conjunction with the FREE, STRING, and |[/O BUFFER commands to 
determine how memory is allocated for your task. 


Format 


CORE 


Syntax Rules 


None. 


General Rules 
1. The CORE command displays the total number of words currently allocated to your task. 


2. The maximum allowable program space is 32K words on RSX—11M/M—PLUS systems and 
31K words on RSTS/E systems, minus the size of your resident library. Consult BASIC on 
RSX—11M/M-—PLUS Systems or BASIC on RSTS/E Systems for more information on program 
space and resident libraries. 


3. You can use the CORE command only when at least one program module has been 
compiled with the /DEBUG qualifier. Note, however, that the number returned by the 
CORE command reflects the memory allocation for the entire task, not just the module 
compiled with /DEBUG. 


4. Knowing the size of core memory can help you control the size of your program and 
optimize accordingly. Consult BASIC on RSX—11M/M-—PLUS Systems or BASIC on RSTS/E 
Systems for information on optimization. 
Examples 


#CORE 
CORE = 7647 
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ERL 


Function 


The ERL command returns the number of the line executing when the last error occurred. 


Format 


ERL 


Syntax Rules 
None. 
General Rules 
1. The ERL command tells you the number of the line executing when the last error occurred. 


2. If no errors have occurred, the result returned by ERL is undefined. 


Examples 
#ERL 
ERL = 1050 


# 
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5.0 ERN (BASIC—PLUS—2) 


Function 


The ERN command returns the 1— to 6—character name of the program module that was executing 
when the last successfully handled error occurred. If a fatal error was not successfully trapped, 
control passes from the debugger to command level. 


Format 


Syntax Rules 
None. 
General Rules 


1. The ERN command returns a module name only when an error has been successfully 
handled. 


2. If no errors have occurred, the result returned by ERN is undefined. 
Examples 


#ERN 
ERN$ = CHECKS 


= 
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Function 


The ERR command returns the error number of the last error that occurred. 


Format 
ERR 


Syntax Rules 
None. 
General Rules 
1. The ERR command tells you the number of the last error. 
2. If no errors have occurred, the result returned by ERR is undefined. 


3. Refer to Appendix B in BASIC on RSTS/E Systems or BASIC on RSX-11M/M-—PLUS Systems 
for a list of errors and their numbers. 


Examples 
#ERR 
ERR = 55 


+ 
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7.0 EXIT (BASIC-PLUS—2) 


Function 


The EXIT command returns control to BASIC if you are executing a program in the BASIC environ- 
ment and to command level if you are executing a task-built program. 


Format 


EXIT 


Syntax Rules 


None. 


General Rules 


1. The EXIT command does not close open channels. 
Examples 


#EXIT 
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8.0 FREE (BASIC—PLUS—2) 


Function 


The FREE command returns the number of words currently available in memory for I/O and string 
operations before BASIC must perform another memory extension. Use the FREE command in con- 
junction with the CORE, STRING, and |/O BUFFER commands to determine how memory is allo- 
cated for your task. 


Format 


Ce ee 
| FREE | 


Syntax Rules 
None. 
General Rules 


1. The FREE command returns an integer corresponding to the number of free words available 
in memory for |/O and string operations. 


2. When string or 1/O operations exceed the available free space, BASIC extends the amount 
of memory allocated for your task. 


3. Knowing the amount of free space available can help you control the size of your program 
and optimize accordingly. Consult BASIC on RSX-11M/M-—PLUS Systems or BASIC on 
RSTS/E Systems for information on optimization. 


Examples 
#FREE 
FREE = 184 


# 
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9.0 |/O BUFFER (BASIC—PLUS—2) 


Function 


The 1/O BUFFER command returns the number of words currently allocated for |/O buffer space. Use 
the 1/O BUFFER command in conjunction with the CORE, STRING, and FREE commands to deter- 
mine how memory is allocated for your task. 


Format 


//O BUFFER 


Syntax Rules 


None. 


General Rules 


1. The [/O BUFFER command tells you the total number of words allocated for 1/O buffer 
space. 


2. Knowing the size of the |/O buffer can help you control the size of your program and 
optimize accordingly. Consult BASIC on RSX-11M/M-—PLUS Systems or BASIC on RSTS/E 
Systems for information on optimization. 


Examples 


#1/0 BUFFER 
I/0 BUFFERS = 1765 
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10.0 LET (BASIC—PLUS—2) 


Function 


The LET command allows you to change the contents of program variables. 


Format 


vbl2 
const 


LET vbl1 = 


Syntax Rules 


1. VbI1 specifies the numeric or string variable you want to change. If you attempt to create a 
new variable with the LET command, BASIC signals “Illegal syntax in LET’. 

2. Const or vbl2 specifies the new value for vb/7. The LET command allows constants or 
variables as arguments but does not allow expressions. 


3. You cannot set string variables to a null string with the LET command. If you try to do so, 
BASIC signals ‘‘Illegal syntax in LET’. However, you can set a variable to the null string in 
your source program and then assign that variable to another variable with the LET 
debugger command. For example: 


1000 NULLS= "" 
1610 A$="HELLO" 
1020 PRINT AS 


Compile or run the program with the /DEBUG qualifier, establish a breakpoint at line 
1020, and set A$ to the null string with the LET command: 


#LET AS = NULLS 


General Rules 


1. You can change only one variable with each LET command. To change more than one 
program variable, you must enter more than one LET command. 


2. When executing a task-built program, you can change program variables only in program 
modules compiled with the /DEBUG qualifier. 


3. You cannot access program variables across program modules. That is, you cannot access 
a variable in SUB1 from the main program or from another subprogram, and you cannot 
access a variable in the main program from a subprogram. 


4. BASIC signals ‘‘Illegal syntax in LET’’ when you try to access a variable across modules or 
in a module not compiled with the /DEBUG qualifier. 
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Examples 
#LET AZ=15% 
#LET NAME$="MITCHELL" 
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11.0 PRINT (BASIC-PLUS—2) 


Function 


The PRINT command allows you to display the current contents of program variables. 


Format 


PRINT vbl 


Syntax Rules 
1. VbI specifies the numeric or string variable you want to display. 


2. The PRINT command does not allow constants or expressions as arguments. 


General Rules 


1. You can display only one variable with each PRINT command. To display more than one 
program variable, you must enter more than one PRINT command. 


2. When executing a task-built program, you can access only those variables contained in 
program modules that have been compiled with the /DEBUG qualifier. 


3. You cannot access variables across program modules. That is, the variable you want to 
display must exist in the current program module. If you try to display a variable in another 
program module, BASIC signals ‘Illegal syntax in PRINT’. 


Examples 


#PRINT C 


23 


# 
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12.0 RECOUNT (BASIC—PLUS—2) 
Function 
The RECOUNT command tells you how many characters were transferred by the last |/O operation. 


Format 


RECOUNT | 


Syntax Rules 


None. 


General Rules 


1. The RECOUNT command tells you how many characters, including blanks and termina- 
tors, were transferred by the last input or output statement. 


2. If your program has open files and reaches the end of the file before closing open channels 
or executing the END statement, the debugger signals ‘’End-of-file on device’. If you then 
try to continue program execution by typing the CONTINUE command, the debugger 
signals ‘“‘Can’t CONTINUE or STEP’’. When you then EXIT the debugger mode, files are not 
closed, and data is not transferred. If you include an error handler to pass control to the 
END statement, BASIC will close files and transfer data. 


Examples 


#RECOUNT 
RECOUNT = i19 


# 
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13.0 REDIRECT (BASIC-PLUS-2) 


Function 


The REDIRECT command allows you to direct all debugging I/O operations to a specified terminal. 


Format 


| REDIRECT term-nam | 
i ec eee ee | 


Syntax Rules 


1. Term-nam specifies the name of an unattached terminal. It must be an unquoted string that 
corresponds to a terminal name, or BASIC signals the error “Cannot open device’. 


General Rules 


1. After you type the REDIRECT command in response to the debugger prompt, all debugger 
1/O is directed to the terminal you specify. The program executes on the terminal that 
issued the RUN command. 


2. Use another REDIRECT command to direct debugger |/O back to the terminal on which 
the program is executing. 


3. You can use the REDIRECT command only when at least one program module has been 
compiled with the /DEBUG qualifier. 


4. If the specified terminal is allocated, the debugger will signal ‘‘Cannot open device’ on 
RSTS/E systems. On RSX—-11M/M-—PLUS systems, the debugger stops executing until the 
specified terminal is available and does not signal an error. 

Examples 


#REDIRECT KB2: 
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14.0 STATUS (BASIC-PLUS-2) 


Function 


The STATUS command returns a word-length integer that contains information about the last opened 


file. 


Format 


STATUS 


Syntax Rules 


None. 


General Rules 


1. 
2: 


398 


The debugger returns the last STATUS word. 


Depending on the error, the STATUS word on RSX—11M/M-—PLUS systems displays a value 
representing one of the following: 


e The RMS—11 primary status field (STS) or the RMS secondary status field (STV). See the 
RMS—11 MACRO User’s Guide for more information. 


© The device characteristics after an RMS—11 OPEN file operation set by the DEV field of 
the FAB. See the RMS—11 MACRO User’s Guide for more information. 


e In the event of a directive error, the Directive Status Word ($DSW) and its corresponding 
error code. See the RSX—11M/M-—PLUS Mini Reference for the error codes. 


e The STATUS field of a QIO. See the RSX—11M/M-PLUS I/O Driver’s Reference Manual 
for more information. 


e The first word of a GETLUN directive describing device characteristics. See the 
RSX—11M/M—PLUS Executive Reference Manual for more information. 


e See BASIC on RSX—11M/M-—PLUS Systems for information on STATUS values set for an 
OPEN file operation with no errors. 


Depending on the error, the STATUS word on RSTS/E systems displays a value representing 
one of the following: 


e The RMS—11 primary status field (STS) or the RMS secondary status field (STV). See the 
RMS—11 MACRO User’s Guide for more information. 


e The device characteristics after an RMS—11 OPEN file operation set by the DEV field of 
the FAB. See the RMS—11 MACRO User’s Guide for more information. 


e For OPEN operations where no errors occur, the status word describes the device charac- 
teristics of the FIRQB and FQFLAG field. The first 7 bits describe the device, and bits 7 
through 15 describe characteristics of the OPEN statement. See the BASIC—PLUS 
Language Manual and the RSTS/E System Directives Manual for more information on 
STATUS values. 
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15.0 STEP (BASIC—PLUS—2) 


Function 


The STEP command causes the program module to execute statement by statement, stopping after a 
specified number of statements have executed. 


Format 


STEP [ int-const ] 


Syntax Rules 


1. Int-const specifies the number of statements to be executed before the program stops. It 
must be a positive integer from 1 to 32767. 


2. STEP with no int-const is the same as specifying STEP 1. Only one statement executes and 
the program then stops. 


3. If you do not include a space between the command and the int-const, only one statement 
executes. 


General! Rules 


1. When executing a task-built program, only statements in program modules compiled with 
the /DEBUG qualifier in effect are counted. If a module not compiled with the /DEBUG 
qualifier executes before a module compiled with the /DEBUG qualifier, the program does 
not stop until the specified number of statements in the module compiled with /DEBUG 


have executed. 


2. Typing a carriage return in response to the # prompt is the same as typing STEP 1 or STEP 
with no int-const. The next statement executes and the program stops. 


3. Typing a line feed in response to the # prompt has no effect. The debugger waits for a 
carriage return and then signals an error. 


Examples 


BREAK at line 1050 statement 1 
#STEP 2 

#CON 

STEP at line 1050 statement 3 


* 
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16.0 STRING (BASIC-PLUS-2) 


s tw wy = = Vw 


Function 


The STRING command tells you how many words are currently allocated for string storage. Use the 
STRING command in conjunction with the CORE, |/O BUFFER, and FREE commands to determine 
how memory is allocated for your task. 


Format 


Syntax Rules 
None. 
General Rules 


1. The STRING command tells you how many words are allocated for string operations for 
your entire task, not just for the currently executing program module. 


2. Knowing how much memory is allocated to string operations can help you control the size 
of your program and optimize accordingly. See BASIC on RSX—11M/M-—PLUS Systems or 
BASIC on RSTS/E Systems for information on optimization. 


Examples 


#STRING 
STRING = 2086 


# 
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17.0 TRACE (BASIC-PLUS-~2) 


Function 


The TRACE command displays line numbers and statement numbers as the program executes. 


Format 


TRACE 


Syntax Rules 


None. 


General Rules 
1. The TRACE command does not affect program execution or breakpoints. 


2. When executing a task-built program, you can use the TRACE command only in program 
modules that have been compiled with the /DEBUG qualifier. 


3. The TRACE command remains in effect until the program module finishes executing, until 
you specify UNTRACE after a program breakpoint, or until] BASIC reaches a module not 
compiied with the /DEBUG qualifier. When BASIC returns to a module compiled with 
DEBUG, tracing resumes. 


Examples 


#TRACE 

#BREAK 300 

#CONT 

at line 100 statement 1 

at line 100 statement 2 

at line 200 statement 1 

BREAK at line 300 statement i 
#BREAK 300 

#CONT 
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Function 


The UNBREAK command disables previously set breakpoints in programs and subprograms. 


Format 


UNBREAK | ON block | 
if ON | stmnt-break.,... | 
CALL 
DEF 
LOOP 


stmnt-break: lin-num [ .stmnt-num J [ ;mod-nam ] 


Syntax Rules 
1. The ON keyword is required to disable block breakpoints. 


2. UNBREAK with no parameters disables all previously specified stmnt-break breakpoints. 
Block breakpoints are not disabled. 


3. Stmnt-break specifies a particular line number or statement where execution is to stop. 
e /in-num specifies a program line. 


e Stat-num specifies a particular statement associated with lin-num. The period (.) is re- 
quired and must immediately follow the line number. BASIC signals an error if you 
include a space between lin-num and stat-num. The listing file lists statements on multi- 
statement lines by number. 


e Mod-nam specifies that the preceding breakpoint is a breakpoint only in the named 
program module. The semicolon (;) is required. 


e You can disable more than one stmnt-break breakpoint with the UNBREAK command, 
but you must separate them with commas. 


¢ Mod-nam specifies a program module compiled with the /DEBUG qualifier in effect. 
When mod-nam is specified, the line number specified is disabled as a breakpoint only 
in the named program. If the breakpoint has not been previously set, BASIC signals an 
error. 


e lf lin-num or stat-num do not exist, the debugger signals the error ‘‘Bad line spec in 
(UN)BREAK”’. 
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General Rules 


None. 
Examples 


#UNBREAK ON LOOP 
#UNBREAK 1005GAMES; 500, 600.2 
#CON 
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UNTRACE 


Function 
The UNTRACE command disables the TRACE command. 


Format 


| UNTRACE | 


Syntax Rules 


None. 


Generai Rules 


1. Enter the UNTRACE command when the program stops executing after encountering a 
specified breakpoint. 


Examples 


#UNTRACE 
#CON 
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Appendix A 
Reserved BASIC Keywords 


%ABORT 
%CDD 
%CROSS 
%ELSE 
%END 
%FROM 
%IDENT 
%IF 
%INCLUDE 
%LET 
%LIST 
%NOCROSS 
%NOLIST 
%PAGE 
%SBITL 


Iravl 
% THEN 


% TITLE 
%VARIANT 
ABORT 
ABS 

ABS% 
ACCESS 
ACCESS% 
ACTIVE 
ALIGNED 
ALLOW 
ALTERNATE 
AND 


BACK 

BASE 

BEL 

BINARY 

BIT 

BLOCK 
BLOCKSIZE 
BS 
BUCKETSIZE 


CHANGE 
CHANGES 
CHECKING 
CHR$ 

CLK$ 

CLOSE 
CLUSTERSIZE 
COM 
COMMON 
COMP% 
CON 
CONNECT 
CONSTANT 
CONTIGUOUS 
COS 

COT 

COUNT 

CR 


CTRLC 
CVT$$ 
CVT$% 
CVT$F 

CVT %$ 
CVTF$ 

DAT 

DAT$ 

DATA 
DATE$ 
DECIMAL 
DECLARE 
DEF 
DEFAULTNAME 
DEL 

DESC 

DET 

DIF$ 

DIM 
DIMENSION 
DOUBLE 
DOUBLEBUF 
DUPLICATES 
DYNAMIC 
ECHO 

EDIT$ 

ELSE 

END 

EQ 

EQV 

ERL 

ERN$ 

ERR 

ERROR 


ERT$ 

ESC 

EXIT 

EXP 
EXPLICIT 
EXTEND 
EXTENDSIZE 
EXTERNAL 


FILE 
FILESIZE 
FILL 
FILL$ 
FILL% 


FOR 
FORMAT$ 
FORTRAN 

FREE 

FROM 

FSP$ 

FSS$ 
FUNCTION 
FUNCTIONEND 
FUNCTIONEXIT 
GE 

GET 

GETRFA 


GFLOAT 


IMP 
INACTIVE 
INDEXED 
INPUT 
INSTR 
INT 
INTEGER 
INV 
INVALID 
ITERATE 
KEY 


MAG 
MAGTAPE 
MAP 
MAR 
MAR% 
MARGIN 
MAT 
MAX 
MID 
MID$ 
MIN 
MOD 
MOD% 
MODE 
MODIFY 
MOVE 
NAME 
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NEXT 
NOCHANGES 
NODATA 
NODUPLICATES 
NOECHO 
NOEXTEND 
NOMARGIN 
NONE 
NOPAGE 
NOREWIND 
NOSPAN 


ONECHR 


OPEN 


ORGANIZATION 
OTHERWISE 
OUTPUT 
OVERFLOW 


PRIMARY 
PRINT 
PROD$ 

PUT 

QUO$ 

RAD$ 
RANDOM 
RANDOMIZE 
RCTRLC 
RCTRLO 
READ 

REAL 
RECORD 
RECORDSIZE 
RECORDTYPE 
RECOUNT 
REF 
REGARDLESS 
RELATIVE 
REM 

REMAP 
RESET 
RESTORE 
RESUME 


Reserved BASIC Keywords 


RETURN 
RFA 

RIGHT 
RIGHT$ 
RND 
ROUNDING 
RSET 

SCALE 
SCRATCH 
SEG$ 

SELECT 
SEQUENTIAL 
SETUP 


STRING 
STRING$ 
SUB 
SUBEND 
SUBEXIT 
SUBSCRIPT 
SUM$ 
SWAP% 
SYS 

TAB 

TAN 
TEMPORARY 
TERMINAL 
THEN 


TYPES 
UNALIGNED 
UNDEFINED 
UNLESS 
UNLOCK 


UNTIL 
UPDATE 
USAGE$ 
USEROPEN 
USING 
USR$ 

VAL 
VAL% 
VALUE 
VARIABLE 
VARIANT 
VFC 
VIRTUAL 
VPS% 

VT 

WAIT 
WHILE 


WINDOWSIZE 


WORD 
WRITE 
XLATE 
XOR 
ZER 


This appendix presents a suggested format for coding BASIC programs. The recommended program 
order and documenting procedures clarify the program’s history, purpose, and logical development. 
This organization also helps the program to run faster and with fewer errors. 


This format is by no means intended to represent the only way of coding BASIC programs. It is a 
sample format that can be adapted and modified to suit individual applications. 


10 ZTITLE “<module-name?> - <terse functional descrirtion>" 
ZSBTTL "“OQuverall descriFtion and modification history" 
ZIDENT "X00,00" 

! 
COPYRIGHT (c} 1982 BY 
DIGITAL EQUIPMENT CORPORATION: MAYNARD: MASS. 


! 

! 

! 

' THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND 
! COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH 
1 THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY 
! OTHER COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAIL- 
! ABLE TO ANY OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFT- 
i WARE IS HEREBY TRANSFERRED. 

I 

! THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT WNO- 
! TICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIP- 
! MENT CORPORATION. 

l 

I 

i 

{ 


DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 
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FACILITY: 
<Facility name> 
ABSTRACT: 


A short 3-6 line abstract of the function of the module. 
full functional specification can be given in 3-6 lines» 


"FUNCTIONAL DESCRIPTION" section below. 
H I Cmargins and tabs] 


ENVIRONMENT: 
CPick one:] 
POP-11 user mode Cwith <Orperating system> derendencies] 
VYAX-1i11 user mode, 
PDP-il and VAX-11 user mode. 
AUTHOR: <Your name>+ CREATION DATE: <dd Mmmmmmmmm vryy> 
MODIFIED BY: 


“Your name>» <dd-Mmm-yy>: VERSION X00.00 
O00 - Original version of module, 


YSBITL "Full description" 


CPick at most one of FUNCTION or SUB below. Include Paramete 


If a 
rePlace 


“ABSTRACT” above by "FUNCTIONAL DESCRIPTION+" and delete the 


rs on 


either. For main Programs,» omit FUNCTION or SUB statement and 


Farameters.:] 


GFLOAT+ HFLOAT+ LONG+ packed (DECIMAL)» SINGLE: 


(STRING)+ or WORD. 


text 


f<arg mech> is d+ ry or v for BY DESC,» BY REF» or BY VALUE. 


<arg form? is <null?> or a for scalar or array, 
H H H Cmargins and tats] 


FUNCTION <datatyrPe> <name> 
SUB <name> 

(<datatyrpe> <Param?+ ! <Description> 

<datatypPe> <param>) ! <Description> 
1++ 
1 FUNCTIONAL DESCRIPTION: 
! 
! A detailed functional description of the routine, This should 
! detail the steps of the Process; the use of external functions 
! and subrrograms (including system services; RTL routiness SYSLIB 
! routines)» and so forth, 
{ i i Cmargins and tabs] i 
| 
! FORMAL PARAMETERS: 
i 
! <namer,<access tyPer<data type>.s,d¢cargy mechd<arg form? 
! A description of the meaning of the Parameters its legal 
! Values, etc. Repeat for each Parameter, If a main Program 
! rather than a function or subroutines use the COMMAND 
! STRUCTURE section, 
! access tyrPe> is m+ r+ or w for modify, read+> or write, 
{ <datatyPpe> is be d+ 9+ he le P+ S+ te or w for BYTE: DOUBLE, 
1 
! 
! 
! 
| 
| 
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Re Re pe 


IMPLICIT INPUTS: 


Describe all uses of the values of global storage 


by the routine, 


IMPLICIT OUTPUTS: 


Describe all modifications to the values of global 


dects used by the routine. 


FUNCTION VALUE: 
COMPLETION CODES: 


turned is a status 


FUNCTION VALUE Ss 


objects used 


Cmargins and tabs] i 


storage ob- 


Cmargdins and tabs] H 


value re- 


indicators use COMPLETION CODE and delete 
if the result of some computations use FUNCTION 


VALUE and delete COMPLETION CODE. 


If a SUB+s delete FUNCTION 


SIDE EFFECTS: 


Describe all functional side effects that are not 


the invocation interface, 
location», Process status, 


Z5BTTL "Declarations" 
! 
1 ENVIRONMENT SPECIFICATION: 
1 
OPTION 
<option clause>» 
<option clause? 
i 
! DATATYPE SPECIFICATION: 
! 
RECORD <name>? 
{fecord declaration? 


END RECORD 


| INCLUDE FILES: 

| 

ZINCLUDE "“<Filespec?" 

I 

!' EQUATED SYMBOLS: 

i 

DECLARE <datatyre> CONSTANT 
Cname> = <valuets 
<name> <value> 


1 
! LOCAL STORAGE: 
I 
DECLARE 
idatatyPe?, 
<name> + 
<name>» 
<datatyPpe> 
<name> + 
<name> 


I 
1 
i 
i 
{ 
{ 
i 
1 
i 
1 
! 
I 
\ 
l 
i 
! If a functions describe the value returned. If the 
! 
! 
| 
! 
! 
! 
! 
{ 
l 
! 
| 
| 
! 
I 


VALUE and enter "None," 
[margins and tabs] H 


evident from 


This includes changes in storage al- 
file operations (including the command 
terminal)» errors signalled: 


etc. 


[margins and tabs] H 


& 

& 
! ¢Description> 

& 
! ¢<Descrirption? Rg 
1 ¢<Description> 

& 

& 
1 <Description: & 
! {<Description> & 

& 
! ¢<DescrirPtion?> & 


1 ¢Description> 
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! GLOBAL STORAGE: 
! 
COMMON (<name>)? 
{<datatyre> 
<name> + 
<name>? 
<datatyre> 
<name>» 
<name> 
MAP (<name>) 
<datatype> 
<name> s 
<name>s 
<datatyPpe> 
<name>> 
<name> 
i 
! EXTERNAL REFERENCES: 
{ 
EXTERNAL <datatyre> CONSTANT 
<name> 
EXTERNAL <datatyPre> 
<name> 
EXTERNAL <datatyre> FUNCTION 
<name> 
(<datatype> BY <mech?>,s 
<datatype> BY <mech?>) 
EXTERNAL SUB 
<name> 
(¢{datatype?> BY <mech?,; 
<datatyrpe> BY <mech?) 
! 
! INTERNAL REFERENCES: 
1 
DECLARE <datatyre> FUNCTION 
<name> 
(<datatyPe>» 
<datatype>) 


<Description?> 


<Description> 
<Description?> 


<Description? 
<Description?> 
<Description> 


<Description> 
<DescriPption> 


<Description> 
<Description> 


<Description?> 
<DescripPption> 


<Function descrirption?> 
<Argument description? 
<Argument description> 


«Function description> 
<Ardument description? 
<Argument description? 


<Function descrirption> 
<Argdument description? 
<Argument description? 


LSBTTL "Environment initialization" 


1+ 


| Set up global error handler 


1. 
ON ERROR GO TO 31000 


CAlternately:; local error handlers can be set up where needed.] 


ZSBTTL "<MaJor section name>" 


<MaJor section name>: 
1+ 


1 <Section description? 


C[Rerpeat once for each maJjJor section.] 


ZSBTTL “Internal subroutine: 
CAccess via GOSUB <symbolic name?] 


<symbolic name>: 
1+ 
i 


FUNCTIONAL DESCRIPTION: 


! 

| 

! IMPLICIT INPUTS: 
| 

1 IMPLICIT OUTPUTS: 
| 


<symbolic name>" 
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RR Re Re Ge fo 


RP Re ee Re ee Pe 


fe Re pe 


Re Re Ee 


30000 


31000 


32767 


! SIDE EFFECTS: 
! 

1. 

RETURN 


ZSBTTL "Internal function - <name>" 


CAccess via tname> (<Params>)] 
DEF <datatype> <name> 
({datatyrPe> <name>; 
<datatype> <name>) 
+ 
FUNCTIONAL DESCRIPTION: 
FORMAL PARAMETERS: 
IMPLICIT INPUTS: 
IMPLICIT QUTPUTS: 


FUNCTION VALUE: 


eS ee er 


SIDE EFFECTS: 

i 

Vue 

END DEF 

Z2SBTTL "RSTS/E CCL entry Point” 


CThis section is for RSTS/E CCL’s only] 


1+ 

! CCL entry Foint: 

fs 

ZSBTTL “Common error handling" 
i+ 

! Common error handling: 

_ 


ZSBTTL "Module end” 
END <FUNCTION: null+ or SUB? 
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<Description> 
«Description: 
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The Master Index contains a list of the major references to subjects in the BASIC Reference Manual, the 
BASIC User’s Guide, and the system-specific manuals. The index uses the following conventions: 


Example Explanation 
1—8t A page number followed by a t indicates a table. 
4—36f A page number followed by an f indicates a figure. 


Entries in the Master Index are also preceded by an acronym indicating which manual the page number 


refers to: 

Acronym Title 
IM BASIC Reference Manual 
UG BASIC User’s Guide 


RSTS BASIC on RSTS/E Systems 
RSX BASIC on RSX Systems 
VMS BASIC on VAX/VMS Systems 


Where a subject references more than one manual, references to the BASIC Reference Manual appear 
first, the BASIC User’s Guide second, and the system-specific manuals appear last in alphabetical order. 


For a more complete list of references, see the individual indexes in the back of each manual. 


XOpu] JOISeyy 


Index 


This index provides a complete cross-reference to the information in this manual. In the index the 
following convention is used: 


Example Explanation 
12t A page number followed by a t indicates a table. 


For material not covered in this manual, see the Master Index in the back of the BASIC Reference 
Manual. The Master Index contains a list of the major references to information throughout the BASIC 


documentation set. 


A 


Abbreviations 
debugger command, 382 
qualifier, 83 

%ABORT, 113 

ABS, 293 

ABS%, 294 

Absolute value 
ABS, 293 
ABS%, 294 
MAG, 331 

ACCESS clause, 241, 258 
APPEND, 241 
MODIFY, 173, 191, 241 
READ, 173, 191, 241 
SCRATCH, 173, 241 
WRITE, 241 

Accessing 
CDD record definitions, 263 
RECORD items, 264, 265 

ACTIVE clause, 249 

Allocating storage 
for arrays, 159 
for FILL items, 141t, 227, 268 
for RECORD structures, 264 
for VARIANT fields, 265 
with COMMON, 139, 142 
with MAP, 210 
with MAP DYNAMIC, 213 
with REMAP, 268 


February 1984 


ALLOW clause, 241 
MODIFY, 174, 192, 241 
NONE, 174, 192, 241 
READ, 174, 192, 241 
WRITE, 241 
Alphanumeric label, 2 
See also Labels 
ALTERNATE KEY clause, 240, 244 
Ampersand (&) 
as a continuation character, 4, 6, 7 
in DATA statements, 143 
AND, 38 
ANSI Minimal BASIC Standard, 84 
ANSI_STANDARD qualifier, 84 
APPEND, 43 to 44 
Arc tangent, 296 
Arithmetic operators, 30, 30t 
Arrays, 27 to 29 
array elements, 27, 159 
assigning values to, 206, 217, 219, 221, 
225, 261 
bounds, 159, 217, 219, 221, 223, 225 
bounds checking, 84 
converting with CHANGE, 136 
creating with COMMON, 140 
creating with DECLARE, 145 
creating with DIM, 158 
creating with MAP, 210 
creating with MAT statements, 216, 219, 
2215. 223; 225 
data type of, 158 
definition of, 27 
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Arrays (Cont.) 
dimensions of, 28, 158 
dynamic, 158, 159, 160 
element zero, 28, 159, 218, 220, 222, 224, 
226, 228 
initialization of, 161, 217 
inversion of, 218 
matrix arithmetic, 217 
naming, 29 
redimensioning with MAT statements, 217, 
218, 219, 221, 225 
size limits, 28 
static, 158, 159 
transposition of, 218 
virtual, 29, 147, 158, 159, 170 
ASCII 
character set, 10 
characters, 24, 36, 299 
conversion, 136, 295, 299 
function, 295 
stream files, 245 
ASSIGN, 45 
Assigning logical names, 45 
Assigning string data 
with LSET, 209 
with RSET, 274 
Assigning values 
to array elements, 206, 217, 219, 221, 225, 
261 
to lexical constants, 121 
with INPUT, 199 
with INPUT LINE, 202 
with LET debugger command, 393 
with LET statement, 206 
with LINPUT, 207 
with LSET, 209 
with MAT INPUT, 219 
with MAT LINPUT, 221 
with MAT READ, 225 
with READ, 261 
with RSET, 274 
Asterisk (*) 
in PRINT USING format field, 255 
with HELP, 69 
Asterisk—filled field 
in PRINT USING, 255 
ATN, 296 
AUDIT qualifier, 84 


B 
Backslash () 


in continued lines, 6 
in multi-statement lines, 5 
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Backslash () (Cont.) 
in PRINT USING format field, 256 
statement separator, 5 
BASIC character set, 10 
BEL, 23 
Binary radix, 21 
Blank—if—zero field 
in PRINT USING, 255 
Block I/O files, 94 
finding records in, 174 
opening, 240 
retrieving records sequentially in, 191 
writing records to, 258 
Block statements 
ending, 162 
exiting, 164 
BLOCKSIZE clause, 243 
Bounds, 27 
default for implicit arrays, 159, 217, 219, 
221,223,225 
maximum, 28 
BOUNDS_CHECK qualifier, 84 
BREAK debugger command, 383 to 384 
BRLRES command, 46 to 47 
BUILD default, 48 
BRLRES qualifier, 90 
BS, 23 
Buckets 
BUCKETSIZE clause, 244 
locking, 174, 192 
unlocking, 174, 182, 192 
BUCKETSIZE clause, 244 
BUFFER clause, 243 
BUFSIZ, 297 
BUILD, 48 
BASIC—PLUS—2 qualifiers, 90t 
BY clauses 
BY DESC, 131, 168, 185, 282 
BY REF, 131, 168, 185, 282 
BY VALUE, 131, 168 
BYTE data type, 11 
BYTE qualifier, 84, 90 


C 


C formatting character 
in PRINT USING, 256 
CALL, 129 to 133 
as a debugger breakpoint, 383 
with SUB, 281 
Calling subprograms, 129, 281 
Caret () 
in PRINT USING format field, 255 
CASE clause, 276 
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CASE ELSE clause, 277 
CCPOS, 298 
CD 
in PRINT USING format field, 255 
CDD 
accessing definitions in, 263 
including definitions from, 7, 84, 88, 119 
Centered field 
in PRINT USING, 256 
CHAIN qualifier, 90, 134 
CHAIN statement, 134 to 135 
CHANGE, 136 to 137 
with NOSETUP, 87 
CHANGES clause, 244 
CHARACTER data type, 23 
Character position 
CCPOS, 298 
of substring, 322, 345 
Character sets 
ASCII, 10 
BASIC, 10 
translating with XLATE, 379 
Characters 
ASCII, 24, 36, 295, 299 
data type suffix, 13 
format in PRINT USING, 255 to 257 
lowercase, 58, 64, 66, 256 
nonprinting, 23 
processing of, 10 
uppercase, 58, 64, 66, 256 
wildcard, 69 
CHR$, 18, 299 
Clauses 
ACCESS, 173, 191, 241, 258 
ACTIVE, 249 
ALLOW, 174, 192, 241 
ALTERNATE KEY, 240, 244 
BLOCKSIZE, 243 
BUCKETSIZE, 244 
BUFFER, 243 
BY, 131, 168, 185, 282 
CASE, 276 
CHANGES, 244 
CLUSTERSIZE, 246 
CONNECT, 245, 246 
CONTIGUOUS, 242, 244, 245 
COUNT, 258, 289 
DEFAULTNAME, 240, 243 
DUPLICATES, 244, 259 
ELSE, 197 
END IF, 197 
EXTENDSIZE, 243, 245, 246 
FILESIZE, 242 
FOR INPUT, 240 
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Clauses (Cont.) 
FOR OUTPUT, 240 
GROUP, 264 
KEY, 172, 190, 271 
MAP, 212, 243 
MODE, 246 
NOREWIND, 243, 245, 247 
NOSPAN, 243 
ORGANIZATION, 240 
OTHERWISE, 236, 237 
PRIMARY KEY, 240, 244, 247 
RECORD, 172, 190, 258, 259 
RECORDSIZE, 212, 242, 258 
RECORDTYPE, 241 
REGARDLESS, 174, 192 
RFA, 172, 190 
STEP, 179 
TEMPORARY, 242 
THEN, 197 
UNLOCK EXPLICIT, 173, 175, 191, 245 
UNTIL, 180 
USEROPEN, 240, 243 
VARIANT, 264 
WHILE, 180 
WINDOWSIZE, 242 
CLOSE, 138 
Closing files, 138 
with END, 162 
CLUSTER qualifier, 90 
CLUSTERSIZE clause, 246 
CMD file, 48 
Colon (:) 
in labels, 2 
Comma (,) 
in DATA, 144 
in DELETE command, 54 
in INPUT, 199 
in INPUT LINE, 202 
in LINPUT, 207 
in LIST, 75 
in MAT PRINT, 224 
in PRINT, 251 
in PRINT USING format field, 255 
$ command, 49 to 50 
Command qualifiers, 83 to 94 
BASIC—PLUS—2, 90t 
VAX—11 BASIC, 84t 
Comment 
field, 8, 267 
in DATA statements, 9, 143 
processing of, 10 
REM, 9, 267 
transferring control to, 8 
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COMMON, 139 to 142 
size, 141 
with FIELD, 170 
Common Data Dictionary, 7 
See also CDD 
COMP%, 300 
Comparing 
numeric strings, 300 
strings, 36 
Comparisons 
EQ, 173, 191 
GE, 173, 191 
GT, 173, 191 
Compilation 
conditional, 117, 128 
control of, 7, 108 
control of listing, 114, 122, 123, 124, 125, 
126, 127 
controlling with OPTION, 249 
including from CDD, 7, 84, 88, 119 
including source code, 7, 119 
terminating with %ABORT, 113 
Compilation qualifiers, 83 to 94 
BASIC—PLUS—2, 90t 
VAX-11 BASIC, 84t 
COMPILE, 51 to 52 
BASIC—PLUS—2 qualifiers, 90t 
DEBUG qualifier, 381 
VAX—11 BASIC qualifiers, 84t 
Compiler directives, 7 
Components, 264 
CON, 217 


of COMMON areas, 141 
string, 5, 30, 34 
Conditional branching 
with IF, 197 
with ON—GOSUB, 236 
with ON—GOTO, 237 
with SELECT, 276 
Conditional compilation, 7 
%VARIANT, 128 
with %IF, 117 
Conditional expressions, 34 to 40 
definition of, 34 
in %LET, 121 
in FOR, 180 
in IF, 197 
in UNLESS, 286 
in UNTIL, 288 
in WHILE, 292 
Conditional loops, 179, 288, 292 
CONNECT clause, 245, 246 
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Constants, 14 to 24 
declaring, 146 
default data type, 15 
definition of, 14 
external, 166 
floating—point, 15 
integer, 17 
lexical, 117, 121 
named, 19 to 21 
numeric, 15 to 18 
packed decimal, 17 
predefined, 23 to 24 
string, 18 to 19 
types of, 14 
CONTIGUOUS clause, 242, 244, 245 
Continuation characters 
ampersand, 6 
backslash, 6 
CONTINUE command, 53 
with RUN, 103 
CONTINUE debugger command, 385 
Continued 
lines, 5 
statements, 4, 5 
string literals, 5 
Conversion 
of array to string variable, 136 
of string variable to array, 136 
Conversion functions 
CVT$%, 304 
CVT$F, 304 
CVT%$, 304 
CVTF$, 304 
DECIMAL, 307 
INTEGER, 325 
NUM$, 339 
NUM1$, 340 
RAD$, 351 
REAL, 354 
STR$, 365 
VAL, 377 
VAL%, 378 
XLATE, 379 
Copying BASIC source text, 7, 119 
CORE debugger command, 386 
COS, 301 
Cosine, 301 
COUNT clause 
with fixed—length records, 258, 289 
with variable-length records, 258, 289 
CPU time, 373 
CR, 24 
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Creating 
arrays, 140, 145, 158, 159, 210, 216, 219, 
221 2239-225 
object modules, 51, 87, 93 
output listing, 86, 92 
strings, 361, 366 
Credit—debit field 
in PRINT USING, 255 
%CROSS, 114 
Cross—reference table 
%CROSS, 114 
CROSS_REFERENCE qualifier, 84, 90 
%NOCROSS, 123 
CROSS_REFERENCE qualifier, 84, 90 
CTRL/C 
resuming after, 302 
trapping, 302, 352 
with RECOUNT function, 355 
with RESUME, 272 
CTRL/Z, 68 
editing command, 63 
with INPUT, 201 
with INPUT LINE, 203 
with LINPUT, 208 
CTRLC, 302 
See also RCTRLC 
Cursor position 
CCPOS, 298 
TAB, 371 
CVT$$, 303 
See also EDIT$ 
CVTxx 
CVT$%, 304 
CVT$F, 304 
CVT%$, 304 
CVTF$, 304 
with FIELD, 169 


D 


DATA, 143 to 144 
See also READ 
comment fields in, 9 
in DEF functions, 151 
in DEF* functions, 155 
in multi-statement lines, 7 
with MAT READ, 225 
with READ, 261 
with RESTORE, 271 
Data types, 10 to 14 
BYTE, 11 
CHARACTER, 23 
DECIMAL, 11 
decimal overflow checking, 87, 249 
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Data types (Cont.) 


defining with RECORD, 263 
DOUBLE, 11 

GFLOAT, 11 

HFLOAT, 711 

in LET, 206 

in logical expressions, 37 

in numeric expressions, 31 
INTEGER, 11 

integer overflow checking, 87, 249 
keywords, 11, 12 

LONG, 11 

numeric literal notation, 21 
precision, 12 

precision in PRINT, 252 

precision in PRINT USING, 254 
promotion rules, 31 to 34 

range, 12 

REAL, 11 

results for DECIMAL data, 33t 
results for GFLOAT and HFLOAT, 32t 
results in expressions, 32t 

RFA, 12 

setting defaults with OPTION, 249 
SINGLE, 11 

size, 12 

storage of, 11, 12 

STRING, 11 

suffix characters, 13 

WORD, 11 


Data typing 


explicit, 13, 14 

implicit, 13 

with declarative statements, 14 
with suffix characters, 13 


Datatype defaults, 13, 14 


BYTE qualifier, 84, 90 

constants, 15 

DECIMAL_SIZE qualifier, 84 
DOUBLE qualifier, 85, 91 
GFLOAT qualifier, 86 

HFLOAT qualifier, 86 

LONG qualifier, 87, 92 

SINGLE qualifier, 88, 94 
TYPE_DEFAULT qualifier, 89, 94 
WORD qualifier, 89, 94 


Data—type functions 


DECIMAL, 307 
INTEGER, 325 
REAL, 354 


Data—type keywords, 11 
Date and time functions 


DATE$, 306 
TIME, 373 
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Date and time functions (Cont.) 
TIMES, 375 
DATE$, 306 
Debit—credit field 
in PRINT USING, 255 
DEBUG qualifier, 84, 91 
with COMPILE, 381 
with RUN, 103, 279, 381 
Debugger 
BASIC—PLUS—2 commands, 381 to 405 
command abbreviations, 382 
effect on task size, 382 
prompt, 381 
Debugging 
changing variable values, 393 
DEBUG qualifier, 84, 91 
disabling of TRACE, 405 
disabling program breakpoints, 384, 403 
displaying program values, 395 
redirecting |/O operations, 397 
resuming execution, 385 
setting program breakpoints, 383 
TRACEBACK qualifier, 88 
tracing statement execution, 402 
with debugger commands, 103, 279 
DECIMAL data type, 11 
constants, 17 
format of, 13 
overflow checking, 87, 249 
promotion rules, 32 
rounding, 87, 249 
storage of, 11 
DECIMAL function, 307 
Decimal radix, 21 
DECIMAL_SIZE qualifier, 84 
Declarative statements 
COMMON, 140 
DECLARE, 145 
EXTERNAL, 166 
MAP, 210 
DECLARE, 145 to 148 
CONSTANT, 20, 24, 146, 147 
FUNCTION, 146, 147 
Declaring 
constants, 20, 146 
DEF functions, 146, 149 
DEF* functions, 153 
external constants, 166 
external subprograms, 185 
external subroutines, 166 
external variables, 166 
RECORD structures, 264 
variables, 145 
Declining features, 85, 91 
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DEF, 149 to 152 


as a debugger breakpoint, 383 

ending, 162 

error handling in, 151, 163, 233, 234, 272 
exiting, 164 

multi-line, 150 

parameters, 150, 151 

recursion in, 151 

transferring control into, 151, 236, 237 
with INPUT, 199 

with INPUT LINE, 202 

with LINPUT, 207 

with NOSETUP, 87 

with READ, 261 


DEF*, 153 to 156 


error handling in, 155, 163 
multi-line, 154 

parameters, 154, 155 
recursion in, 155 
transferring control into, 155 


DEFAULTNAME clause, 240, 243 
Defaults 


BRLRES, 46 

BUCKETSIZE clause, 244 

BUILD, 48 

CLUSTERSIZE clause, 246 

COMMON name, 140 

COMPILE, 51 

constants, 15 

data type, 13, 14, 249 

DEFAULTNAME clause, 243 

displaying, 109 

DSKLIB, 55 

EDIT, 57 

error handling, 233 

file name, 79, 82, 95, 97, 102, 104, 111, 
134, 240 

floating—point constants, 15 

implicitly declared variables, 26, 27 

integer constants, 17 

LIBRARY, 73 

listing file, 51, 84, 86, 90, 92 

LOAD, 77 

numeric constants, 15 

object module name, 51, 87, 93 

ODLRMS, 80 

overriding with BUILD, 48 

overriding with COMPILE, 51 

overriding with RUN, 102 

parameter passing mechanisms, 132t, 133t, 
168, 185, 282 

radix, 21 

RECORDSIZE clause, 242 

RESEQUENCE, 98 
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Defaults (Cont.) 
RMSRES, 100 
SCALE, 105 
scale factor, 249 
SEQUENCE, 107 
SET, 108 
setting with BRLRES, 46 
setting with DSKLIB, 55 
setting with LIBRARY, 73 
setting with ODLRMS, 80 
setting with OPTION, 248 
setting with RMSRES, 100 
SHOW, 109 
WINDOWSIZE clause, 242 
DEFINE editing command, 61 
Defining 
COMMON storage, 139 
data structures, 263 
labels, 2 
MAP DYNAMIC storage, 213 
MAP storage, 210 
DEL, 24 
DELETE command, 54 
DELETE statement, 157 
with UNLOCK, 287 
Deleting 
files, 111, 205, 242 
program lines, 54 
records, 157, 275 
Delimiter 
EDIT, 57 
in DATA, 144 
string literal, 18 
SUBSTITUTE editing command, 66 
Descriptors, 131, 168, 185, 282 
DET, 308 
Determinant, 308 
DIF$, 309 
DIM, 158 to 161 
executable, 159, 160 
nonvirtual, nonexecutable, 159 


used with MAT statements, 217, 218, 219, 


221,223 

virtual, 159 

with NOSETUP, 87 
DIMENSION, 158 to 161 

See also DIM 
Dimensions 

of arrays, 28, 158 
Disk—resident libraries 

overriding defaults, 91 

setting defaults, 55 
Displaying 

defaults, 109 
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Displaying (Cont.) 
program lines, 75. 

Documentation 
on-line, 69 


program, 8 to 10 


Dollar sign ($) 
in DECLARE, 145, 146 
in DEF names, 149, 150 
in DEF* names, 153, 154 
in FUNCTION names, 184 
in MAP DYNAMIC variables, 213 
in PRINT USING format field, 255 
in SUB names, 281 
in variable names, 25, 26 
suffix character, 13 
DOUBLE data type, 11 
DOUBLE qualifier, 85, 91 
DSKLIB command, 55 to 56 
BUILD default, 48 
DSKLIB qualifier, 91 
DUMP qualifier, 91 
DUPLICATES clause, 244, 259 
Dynamic 
arrays, 158, 159, 160 
mapping, 169, 213, 268 
storage, 213, 268, 269 


E 


E formatting character 

in PRINT USING format field, 256 
E mathematical constant, 316 
E notation, 16 

field in PRINT USING, 255 


in numeric literal notation, 21 
in PRINT USING format field, 256 
numbers in, 16t 
with PRINT, 252 
with STR$, 365 

ECHO, 310 
See also NOECHO 

EDIT, 57 to 60 

EDIT$, 311 
values, 311t 

Editing 
program lines, 57 
strings, 311, 376 
with a text editor, 58 
with editing commands, 58 

Editing commands, 60t 
DEFINE, 61 
EXECUTE, 62 
EXIT, 63 
FIND, 64 
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Editing commands (Cont.) 
INSERT, 65 
SUBSTITUTE, 66 
ELSE clause, 197 
END, 162 to 163 
DEF, 150, 154, 162 
FUNCTION, 162, 184 
GROUP, 162 
IF, 162, 197 
RECORD, 162 
SELECT, 162, 277 
SUB, 162, 281 
VARIANT, 162 
Ending 
multi-line DEF, 150, 162 
multi-line DEF*, 154 
programs, 162 
statement blocks, 162 
subprograms, 162, 184, 281 
EQ, 173, 191 
Equivalence name, 45 
EQV, 38 
ERL debugger command, 387 
ERL function, 312 
with labels, 2 
with NOLINE qualifier, 86, 92 
with RESEQUENCE, 99 
ERN debugger command, 388 
ERN$, 313 
ERR debugger command, 389 
ERR function, 314 
Error 
number, 314 
text, 315 
Error handling 
disabling, 235 
ERL, 312 
ERN$, 313 
ERR, 314 
ERT$, 315 
in DEF functions, 151, 163, 233, 234 
in DEF* functions, 155, 163 
in FOR—NEXT loops, 272 
in subprograms, 163, 164, 185, 233 
in UNTIL loops, 272 
in WHILE loops, 272 
ON ERROR GO BACK, 233 
ON ERROR GOTO, 234 
ON ERROR GOTO 0, 235 
recursion in, 234 
RESUME, 272 
Error handling functions 
CTRLC, 302 
ERL, 312 
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Error handling functions (Cont.) 
ERN$, 313 
ERR, 314 
ERT$, 315 
RCTRLC, 352 
ERT$, 315 
ESC, 24 
Evaluation 
of expressions, 40 to 42 
of logical expressions, 38 to 40 
of numeric relational expressions, 35 
of operators, 40 
of SELECT statements, 277 
of string relational expressions, 36 
Exclamation point (!) 
in comment fields, 8 
in PRINT USING format field, 256 
Executable 
DIM, 159 
statements, 3 
EXECUTE editing command, 62 
Execution 
continuing, 53, 103, 385 
of multi—statement lines, 5 
of statements, 5 
of system commands, 49 
program, 102 
stopping, 53, 103, 279, 383, 400 
suspending, 278, 291 
EXIT command, 68 
EXIT debugger command, 390 
EXIT editing command, 63 
EXIT statement, 164 to 165 
DEF, 164 
FUNCTION, 164 
SUB, 164 
Exiting 
DEF functions, 164 
loops, 164 
statement blocks, 164 
subprograms, 164 
EXP, 316 
Explicit 
creation of arrays, 158 
data typing, 13, 14, 89, 94, 248 
declaration of variables, 27 
literal notation, 21 to 23 
loop iteration, 204 


record locking, 157, 173, 174, 175, 191, 


1922245 
Exponential notation, 16, 252 
in PRINT USING, 255 
numbers in, 16t 
with PRINT, 252 
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Exponentiation, 316 

Expressions, 30 to 42 
conditional, 34 to 40 
conditional in %LET, 121 
definition of, 30 
evaluation of, 40 to 42 
lexical, 117, 121, 128 
logical, 37 to 40 
mixed—mode, 31 to 34 
numeric, 30 to 34 
numeric relational, 35 
operator precedence in, 40, 41t 
parentheses in, 41 
relational, 35 to 37 
string, 34 
string relational, 36 
types of, 30 

EXTEND qualifier, 91 

Extended field 
in PRINT USING, 256 


EXTENDSIZE clause, 243, 245, 246 


EXTERNAL, 166 to 168 


BASIC-PLUS—2 parameter passing 


mechanisms, 133t 
CONSTANT, 20, 166 
FUNCTION, 166 
parameters, 167 
SUB, 166 


VAX-11 BASIC parameter passing 


mechanisms, 132t 
with NOSETUP, 87 
External 
constants, 20, 166 
functions, 166 
subroutines, 166 
variables, 26, 166 
Extracting substrings 
with LEFT$, 326 
with MID$, 335 
with RIGHT$, 356 
with SEG$, 358 


F 


Features 
declining, 85, 91 
FF, 24 
FIELD, 169 
Fields 
asterisk-filled, 255 
blank—if—zero, 255 
centered, 256 
comment, 8 
credit or debit, 255 
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Fields (Cont.) 
exponential, 255 
extended, 256 


floating dollar sign, 255 


! 
GROUP, 264 


left-justified, 256 
one—character, 256 
right—justified, 256 


trailing minus sign, 255 


VARIANT, 264 
zero—fill, 255 
File attributes 


BLOCKSIZE clause, 243 
CLUSTERSIZE clause, 246 
CONTIGUOUS clause, 242 
EXTENDSIZE clause, 243 
FILESIZE clause, 242 


magnetic tape, 243 

MODE clause, 246 
File names 

BUILD default, 48 


CHAIN statement default, 134 
COMPILE default, 51 


LOAD default, 77 
NEW default, 79 
OLD default, 82 
OPEN default, 240 


RENAME default, 95 
REPLACE default, 97 


RUN default, 102 
SAVE default, 104 


UNSAVE default, 111 


File—related functions 
BUFSIZ, 297 


CCPOS, 298 


FSP$, 319 
FSS$, 320 
GETRFA, 321 
MAGTAPE, 332 
MAR, 334 
ONECHR, 341 


RECOUNT function, 355 


STATUS, 363 
Files 
ASCII stream, 245 


block 1/O, 94, 174, 191, 240, 258 


closing, 138 


deleting, 111, 205, 242 
deleting records in, 157, 275 
finding buffer size, 297 
%INCLUDE, 98, 119, 120 


indexed, 92, 157, 174, 191, 240, 243, 244, 


258, 271, 290 


magnetic tape, 243, 271, 332 
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Files (Cont.) 
opening, 238 


relative, 93, 157, 173, 191, 240, 242, 244, 


258, 290 
renaming, 230 
restoring data, 271 


RMS sequential stream, 245 
sequential, 93, 173, 191, 240, 242, 243, 


251, 258, 275, 289 


terminal-format, 199, 202, 207, 215, 219, 
221, 223, 232, 244, 251 


virtual, 94, 242, 271 
FILESIZE clause, 242 
FILL, 139, 210, 227, 268 
FILL items 

formats and storage, 141t 

in COMMON, 139 

in MAP, 210 

in MOVE, 227 

in REMAP, 268 
FILL$, 139, 210, 227, 268 
FILL%, 139, 210, 227, 268 
FIND editing command, 64 


FIND statement, 171 to 176 


with PUT, 259 
with UNLOCK, 287 
with UPDATE, 289 
Finding 
records, 174 
string length, 327 
substrings, 322, 345 
virtual address, 328 
FIX, 317 
compared with INT, 324 
FLAG qualifier 
BP2COMPATIBILITY, 85 
DECLINING, 85, 91 
Floating dollar sign field 
in PRINT USING, 255 
Floating-point 
constants, 15 
data types, 11 
promotion rules, 31 
variables, 26 
FNEND, 177 
See also END 
FNEXIT, 178 
See also EXIT 
FOR clause 
INPUT, 240 
OUTPUT, 240 
FOR statement, 179 to 181 


FOR-NEXT loops, 179 to 181, 231 


conditional, 179 
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FOR-—NEXT loops (Cont.) 
error handling in, 272 


exiting, 164 ‘ 
explicit iteration of, 204 
nested, 179 
transferring control into, 180, 195, 196, 236, 
237 
unconditional, 179 
Format 
characters in PRINT USING, 255 
E, 16,252 


explicit literal notation, 21 
exponential, 16, 252 

for SET qualifiers, 83 

of comment field, 8 

of compiler directives, 7 

of data, 11 

of data in DATA statements, 144 
of DECIMAL data, 13 

of empty statements, 10 

of external constant name, 21 
of external variable names, 26 
of FILL items, 141t 

of floating-point constants, 15 
of implicitly declared variables, 26, 27 
of integer constants, 17 

of internal constant name, 19 
of internal variable names, 25 
of keywords, 3 

of labels, 2 

of line numbers, 1 

of logical expressions, 37 

of multi-line REM, 9, 267 

of multi-statement lines, 6, 7 

of numeric expressions, 30 

of packed decimal constants, 17 
of program lines, 1 to 8 

of relational expressions, 35 

of statements, 3 

of string constants, 18 

of subscripted variables, 28 


Radix—50, 351 
FORMAT$, 318 
Formatting 


MAT PRINT output, 224 

numeric output, 255 to 256 

PRINT output, 251, 253 

storage with LSET, 209 

storage with RSET, 274 

string output, 256 to 257 

with FORMAT$, 318 

with PRINT USING, 254 to 257 
FREE debugger command, 391 
FREE statement, 182 
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FSP$, 319 
FSS$, 320 
FUNCTION, 183 to 186 
BASIC—PLUS—2 parameter passing 
mechanisms, 133t 
parameters, 184 
VAX—11 BASIC parameter passing 
mechanisms, 132t 
Function codes 
MAGTAPE, 332t 
FUNCTIONEND, 187 
See also END 
FUNCTIONEXIT, 188 
See also EXIT 
Functions 
declaring, 146, 149, 153 
external, 166 
initialization of, 151, 155 
invocation of, 151, 155 
lexical, 89, 94, 117, 121, 128 
naming, 149, 153 
parameters, 150, 154 
user-defined, 149, 153 


G 


GE, 173, 191 
GET, 189 to 194 

with PUT, 259 

with UNLOCK, 287 

with UPDATE, 289 
GETRFA, 321 
GFLOAT data type, 11 
GFLOAT qualifier, 86 
GOSUB, 195 

with RETURN, 273 
GOTO, 196 
GROUP clause, 264 
GT, 173, 191 


H 


Halting program execution, 53, 279, 383, 400 
HELP, 69 to 70 
Hexadecimal radix, 21 
HFLOAT data type, 11 
HFLOAT qualifier, 86 
HT, 23 
Hyphen (-) 
in DELETE command, 54 
in LIST command, 75 
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1/O 
characters transferred, 355 
closing files, 138, 162 
deleting records, 157 
dynamic mapping, 268 
finding records, 173 
getting records, 191 
|/O BUFFER debugger command, 392 
locking records, 173, 174, 191, 192, 245 
matrix, 337, 338 
moving data, 227 
opening files, 238 
RECOUNT debugger command, 396 
retrieving records, 191 
STATUS debugger command, 398 
unlocking records, 182, 245, 287 
updating records, 289 
with CHAIN, 135 
writing records, 258 
1/O BUFFER debugger command, 392 
%IDENT, 115 to 116 
IDENTIFY, 71 
Identifying module version, 115 
Identity matrix, 217 
IDN, 217 
%IF—% THEN—%ELSE—%END %IF, 117 to 118 
with RESEQUENCE, 98 
IF-THEN—ELSE, 197 to 198 
labels in, 2 
multi-line format, 6 
Immediate mode, 53, 103 
IMP, 38 


Imarnlinit 


EVbipetic 
continuation of lines, 6 
creation of arrays, 159, 217, 219, 221, 223, 
225 
data typing, 13, 147 
declaration of variables, 26 to 27 
%INCLUDE, 119 to 120 
with RESEQUENCE, 98 
IND qualifier, 92 
Indexed files 
ALTERNATE KEY clause, 244 
BUCKETSIZE clause, 244 
CHANGES clause, 244 
deleting records in, 157 
DUPLICATES clause, 244 
finding records in, 174 
IND qualifier, 92 
MAP clause, 243 
opening, 240 
PRIMARY KEY clause, 244 
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Indexed files (Cont.) K 
restoring data in, 271 


retrieving records sequentially in, 191 KEY clauses 
segmented keys in, 244 ALTERNATE, 240, 244 
updating, 290 in FIND, 172 
writing records to, 258 in GET, 190 
Initialization in RESTORE, 271 
in subprograms, 185, 282 PRIMARY, 240, 244, 247 
of arrays, 217 segmented keys, 244 
of DEF functions, 151 Keywords 
of DEF” functions, 155 data-type, 11 
of dynamic arrays, 161 definition of, 3 
of variables, 29, 147 function of, 3 
of variables in COMMON, 142 in RECORD, 264 
of variables in MAP, 212 restrictions, 3 
of virtual arrays, 160 spacing requirements, 4, 4t 
INPUT, 199 to 201 KILL, 205 
INPUT LINE, 202 to 203 
Inputting data L 
ONECHR, 341 
with INPUT, 199 L formatting character 
with INPUT LINE, 202 in PRINT USING, 256 
with LINPUT, 207 Labels 
INQUIRE, 72 defining, 2 
See also HELP format of, 2 
INSERT editing command, 65 function of, 2 
Instance, 264 referencing, 2 
RECORD, 264 transferring control to, 195, 196, 236, 237 
INSTR, 322 to 323 with ITERATE, 204 
See also POS LEFT$, 326 
INT, 324 See also SEG$ 
Integer Left-justification 
constants, 17 PRINT USING format field, 256 
data types, 11 with LSET, 209 
overflow checking, 87, 249 LEN, 327 
promotion rules, 31 Length 
suffix character, 13 label, 2 
variables, 27 of STRING data, 12 
INTEGER data type, 11 variable names, 25 
INTEGER function, 325 %LET, 121 
INV, 218 LET debugger command, 393 to 394 
Inverting arrays, 218, 308 LET statement, 206 
ITERATE, 204 Letters 
Iteration lowercase, 10, 58, 64, 66, 256 
of FOR loops, 180 uppercase, 10,.58, 64, 66, 256 
of loops, 204 Lexical 
of UNTIL loops, 288 constants, 117, 121 
of WHILE loops, 292 expressions, 117, 121, 128 
functions, 89, 94, 117, 121, 128 
J operators, 117, 121 
order, 8 
Justifying strings LF, 24 
with LSET, 209 Libraries 
with RSET, 274 clustering, 90 
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Libraries (Cont.) 
disk-resident, 55 
memory-resident, 46, 73 
RMS, 100, 101t 
setting defaults with DSKLIB, 55 
setting defaults with LIBRARY, 73 
LIBRARY command, 73 to 74 
BUILD default, 48 
LIBRARY qualifier, 92 
Line numbers 
automatic sequencing, 107 
format of, 1 
function of, 2 
in %INCLUDE file, 98, 119 
in object modules, 86, 92 
in RESEQUENCE, 98 
range of, 1 
LINE qualifier, 86, 92, 134 
with debugger commands, 387, 388 
with ERL, 312 
Line terminator, 1, 7, 10 
with DATA statements, 143 
with INPUT, 200 
with INPUT LINE, 203 
with LINPUT, 208 
Lines 
continued, 5 
deleting, 54 
displaying, 75 
editing, 57 
elements of, 1 
format of, 1 to 8 
length of, 1 
muiti-statemeni, 5 to 7 
order of, 8, 98 
single-statement, 4 
terminating, 1, 7, 10 
LINPUT, 207 to 208 
%LIST, 122 
LIST command, 75 to 76 
LIST qualifier, 86, 92 
Listing file 
control of, 7, 88, 114, 122, 123, 124, 125 
creating, 86, 92 
% CROSS, 114 
CROSS_REFERENCE qualifier, 84, 90 
defaults, 51, 84, 86, 90, 92 
included code, 119 
%LIST, 122 
%NOCROSS, 123 
%NOLIST, 124 
%PAGE, 125 
%SBTIL, 126 
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Listing file (Cont.) 
setting page size, 93 
setting width, 94 
subtitle, 126 
TITTLE, 127 
title, 127 
version identification, 115 
LISTNH, 75 
See also LIST 
Literal 
explicit notation, 21 
numeric, 15 
string, 5, 10, 18, 37, 255, 257 
LOAD, 77 
with RUN, 103 
with SCRATCH, 106 
LOC, 328 
Local copy, 131 
Locating records 
by KEY, 172, 174, 190, 192 
by RECORD number, 172, 190 
by RFA, 172, 174, 190, 192 
sequentially, 172, 173, 190, 191 
with FIND, 171 
with GET, 189 
LOCK, 78 
See also SET 
Lock checking 
REGARDLESS clause, 174, 192 
Locking records, 245 
with FIND, 173, 174, 175 
with GET, 191, 192 
LOG, 329 
LOG10, 330 


Logarithm 


common, 330 
natural, 329 

Logical expressions, 37 to 40 
compared with relational, 40 
data types in, 37 
definition of, 34 
evaluation of, 38 to 40 
format of, 37 
logical operators, 38t 
truth tables, 38t 
truth tests, 38 

Logical name, 45 

Logical operators, 38t 

LONG data type, 11 

LONG qualifier, 87, 92 

Loops 
as debugger breakpoints, 383 
conditional, 179 
exiting, 164 
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Loops (Cont.) 
FOR—NEXT, 179 
iteration of, 180, 204, 288, 292 
nested FOR—NEXT, 179 
unconditional, 179 
UNTIL, 288 
WHILE, 292 

Lowercase letters 
in EDIT, 58 
in FIND editing command, 64 
in PRINT USING, 256 
in SUBSTITUTE editing command, 66 
processing of, 10 

LSET, 209 


MACHINE_CODE qualifier, 87 

MACRO qualifier, 92 

MAG, 331 

Magnetic tape files 
BLOCKSIZE clause, 243 
MAGTAPE, 332 
NOREWIND clause, 243 
RESTORE, 271 

MAGTAPE, 332 to 333 
function codes, 332t 


performing functions in VAX—11 BASIC, 


333t 
MAP clause, 212, 243 
MAP DYNAMIC, 213 to 214 
with REMAP, 268, 269 
MAP qualifier, 93 
MAP statement, 210 to 212 
FILL item formats and storage, 141t 
with FIELD, 170 
with MAP DYNAMIC, 214 
with REMAP, 268 
Mapping 
dynamic, 169, 213, 268 
static, 210 
MAR, 334 
MAR%, 334 
MARGIN, 215 
See also NOMARGIN 
with PRINT, 251 
Margin 
width, 215, 232, 251, 334 
MAT, 216 to 218 
with DET, 308 
with FIELD, 170 
with NOSETUP, 87 
MAT INPUT, 219 to 220 
with NOSETUP, 87 
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MAT LINPUT, 221 to 222 
with NOSETUP, 87 
MAT PRINT, 223 to 224 
with NOSETUP, 87 
MAT READ, 225 to 226 
with NOSETUP, 87 
Matrix, 28 
identity, 217 
Matrix functions 
DET, 308 
NUM, 337 
NUM2, 338 
Matrix operations 
arithmetic, 217 
assigning values, 219, 221, 225 
1/O, 337, 338 
inversion, 218, 308 
printing, 223 
redimensioning, 219, 221, 223, 225 
scalar multiplication, 218 
transposition, 218 
Memory 
allocation, 386, 391, 392, 401 
clearing with SCRATCH, 106 
DUMP qualifier, 91 
effect of debugger on, 382 
Memory-resident libraries 
clustering, 90 
overriding defaults, 90, 92 
setting defaults with BRLRES, 46 
setting defaults with LIBRARY, 73 
Merging programs, 43 
MiD$, 335 
See also SEG$ 
Minus sign (-) 
in numeric literal notation, 21 
in PRINT USING format field, 255 
Mixed-mode expressions, 31 to 34 
MODE clause, 246 
Modifiable parameters, 131 
Modifiers 
FOR, 179 
IF, 197, 198 
UNLESS, 286 
UNTIL, 288 
WHILE, 292 
MOVE, 227 to 229 
FILL item formats and storage, 141t 
with FIELD, 170 
with NOSETUP, 87 
Multi-line 
DEF, 149, 150 
DEF”, 153, 154 
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Multi-statement lines, 5 to 7 Nonexecutable statements (Cont.) 


backslash in, 5 DATA, 143 

branching to, 6 DECLARE, 147 

execution of, 5 DIM, 159 

format of, 6, 7 EXTERNAL, 168 

implicit continuation, 6 MAP, 211 

transferring control to, 5 MAP DYNAMIC, 214 

REM, 267 
N with UNLESS, 286 
Nonmodifiable parameters, 131 

NAME AS, 230 Nonprinting characters 
Named constants, 19 to 21 processing of, 10 

changing, 19 using, 10 

external, 20, 166 Nonvirtual DIM, 159 

internal, 19, 146 NOREWIND ciause, 243, 245, 247 
Naming NOSPAN clause, 243 

arrays, 29 NOT, 38 

COMMON areas, 140 evaluation of, 41 

constants, 15, 19, 146 Notation 

DEF functions, 149 E, 16, 16t, 252, 255, 256 

DEF* functions, 153 explicit literal, 21 to 23 

external constants, 20, 166 exponential, 16, 252 

external functions, 166 NUL, 10, 18 

external subroutines, 166 NUL$, 217 

external variables, 26, 166 NUM, 337 

FUNCTION subprograms, 184 after MAT INPUT, 220 

functions, 146 after MAT LINPUT, 221 

internal constants, 19, 146 after MAT READ, 225 

internal variables, 25 NUM$, 339 

lexical constants, 121 NUM1$, 340 

MAP areas, 210 compared with STR$, 365 

programs, 79, 95 NUM2, 338 

SUB subprograms, 281 after MAT INPUT, 220 

subprograms, 130 after MAT LINPUT, 222 

variables, 145 after MAT READ, 226 ; 
Nesting Numbers 

FOR-NEXT loops, 179 random, 260, 357 

IF, 197 sign of, 359 

SELECT, 277 Numbers in E notation, 16t 
NEW, 79 Numeric constants, 15 to 18 
NEXT, 231 Numeric conversion, 136 

with FOR, 180 Numeric expressions, 30 to 34 

with UNTIL, 288 format of, 30 

with WHILE, 292 promotion rules, 31 to 34 
%NOCROSS, 123 result data types, 32t 
NOECHO, 336 results for DECIMAL data, 33t 

See also ECHO results for GFLOAT and HFLOAT, 32t 
NOLINE qualifier, 279 Numeric functions, 304 
%NOLIST, 124 ABS, 293 
NOMARGIN, 232 ABS%, 294 

See also MARGIN DECIMAL, 307 
Nonexecutable DIM, 159 FIX, 317 
Nonexecutable statements, 3, 8 INT, 324 

COMMON, 141 LOG, 329 
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Numeric functions (Cont.) 
LOG10, 330 
MAG, 331 
RND, 357 
SGN, 359 
SQR, 362 
SWAP%, 368 
Numeric literal notation, 21 to 23 
Numeric operator precedence, 41t 
Numeric precision 
with PRINT, 252 
with PRINT USING, 254 
Numeric relational expressions 
evaluation of, 35 
operators, 35t, 35 
Numeric string functions 
CHR$, 299 
COMP%, 300 
DECIMAL, 307 
DIF$, 309 
FORMAT$, 318 
INTEGER, 325 
NUM$, 339 
NUM1$, 340 
PLACE$, 342 
PROD$, 347 
QUO$, 349 
REAL, 354 
STR$, 365 
SUM$, 367 
VAL, 377 
VAL%, 378 
Numeric strings 
comparing, 300 
precision, 309, 342, 347, 349, 367 
rounding, 342, 347, 349 
rounding and truncation values, 344t 
truncating, 342, 347, 349 


O 


Object module 
creating, 51, 87, 93 
default name, 51, 87, 93 
line numbers in, 86, 92 
loading, 77 
version identification, 115 
OBJECT qualifier, 87, 93 
Object Time System (OTS), 55 
Octal radix, 21 
ODL file, 48, 81t 
overriding defaults, 93 
RMS libraries, 101t 
setting defaults, 80 
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ODLRMS command, 80 to 81 
BUILD default, 48 
ODLRMS qualifier, 93 
OLD, 82 
with RUN, 103 
ON ERROR GO BACK, 233 
with END, 162 
with NOSETUP, 87 
ON ERROR GOTO, 234 
with END, 162 
with NOSETUP, 87 
ON ERROR GOTO 0, 233, 235 
with END, 162 
with NOSETUP, 87 
ON-—GOSUB—OTHERWISE, 236 
with RETURN, 273 
ON-GOTO—OTHERWISE, 237 
On-line documentation, 69 
One-character 
input, 341 
PRINT USING format field, 256 
ONECHR, 341 
OPEN, 238 to 247 
with STATUS, 363 
Opening files, 238 to 247 
with USEROPEN clause, 243 
Operator precedence, 30, 40, 41t 
Operators 
arithmetic, 30, 30t 
evaluation of, 40 
lexical, 117, 121 
logical, 38t 
numeric operator precedence, 41t 
numeric relational, 35t 
precedence of, 30, 40, 41t 
string relational, 37t 
OPTION, 248 to 250 
OR, 38 
Order 
lexical, 8 
ORGANIZATION clause, 240 
OTHERWISE clause, 236, 237 
Output 
formatting with FORMAT$, 318 
formatting with PRINT USING, 254 to 256 
Output listing 
creating, 86, 92 
cross-reference table, 84, 90, 114, 123 
default, 51, 84, 90 
%LIST, 122 
%NOLIST, 124 
%PAGE, 125 
%SBTTL, 126 
setting page size, 93 
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Output listing (Co 
setting width, 94 
%TITLE, 127 
Overflow checking, 87, 249 
OVERFLOW quaiifier 
DECIMAL, 87 
INTEGER, 87 
Overlay description file, 80 
See also ODL file 
Overlaying 
COMMON areas, 142 
MAP areas, 211 
Overriding defaults 
with BRLRES qualifier, 90 
with BUILD, 48 
with COMPILE, 51 
with DECLARE, 145, 148 
with DSKLIB qualifier, 91 
with EXTERNAL, 166 
with LIBRARY qualifier, 92 
with ODLRMS qualifier, 93 
with RMSRES qualifier, 93 
with RUN, 102 


P 


Packed decimal, 11 

See also DECIMAL data type 
Padding 

in string relational expressions, 36 

in virtual arrays, 160 
%PAGE, 125 
PAGE_SIZE qualifier, 93 
Parameter passing mechanisms 

BASIC—PLUS—Z, 133% 

CALL, 131 

DEF, 151 

DEF*, 155 

EXTERNAL, 168 

FUNCTION, 185 

SUB, 282 

VAX-11 BASIC, 132t 
Parameters 

CALL, 131 

DEF, 150, 151 

DEF*, 154, 155 

EXTERNAL, 167 

function, 150, 154 

FUNCTION subprograms, 184 

modifiable, 131 

nonmodifiable, 131 

SUB subprograms, 281 
Parentheses 

in array names, 27 
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Parentheses (Cont.) 
in expressions, 30, 40 
Percent sign (%) 
in DATA statements, 17, 143 
in DECLARE, 145, 146 
in DEF names, 150 
in DEF* names, 154 
in FUNCTION names, 184 
in MAP DYNAMIC variables, 213 
in PRINT USING format field, 255 
in SUB names, 281 
in variable names, 25, 26 
suffix character, 13 
Period (.) 
in PRINT USING format field, 255 
in variable names, 25 
PI, 24 
PLACE$, 342 to 344 
rounding and truncation values, 344t 
Plus sign () 
in string concatenation, 34 
POS, 345 to 346 
Pound sign () 
debugger prompt, 381 
in PRINT USING format field, 255 
Precedence 
numeric operator, 41t 
operator, 30, 40 
Precision 
in PRINT, 252 
in PRINT USING, 254 
NUM$, 339 
NUM1$, 340 
of data types, 12 


of numeric strings, 309, 342, 347, 349, 367 
Predefined constants, 23 to 24 

function of, 23 
PRIMARY KEY clause, 240, 244, 247 
PRINT debugger command, 395 
PRINT statement, 251 to 253 

with TAB, 371 
PRINT USING, 254 to 257 
Print zones 

in MAT PRINT, 224 

in PRINT, 251 
Printing 

to a terminal, 251 

to a terminal-format file, 251 
Processing 

INPUT data, 200 

INPUT LINE data, 203 

LINPUT data, 208 

multiple record streams, 245 

of comments, 10 
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Processing (Cont.) 
of lowercase letters, 10 
of nonprinting characters, 10 
of statements, 8 
of string constants, 18 
of string literals, 1 
of uppercase letters, 10 
records, 189, 258, 289 
PROD$, 347 to 348 
rounding and truncation values, 344t 
Program control statements 
END, 162 
EXIT, 164 
FOR, 179 
GOSUB, 195 
GOTO, 196 
IF, 197 
ITERATE, 204 
ON-—GOSUB, 236 
ON-GOTO, 237 
RESUME, 272 
RETURN, 273 
SELECT, 276 
SLEEP, 278 
STOP, 279 
UNTIL, 288 
WAIT, 291 
WHILE, 292 
Program documentation, 8 to 10 
Program elements, 1 to 42 
Program execution 
continuing, 53, 103, 385 
initiating with RUN, 102 
stopping, 53, 103, 279, 383, 400 
suspending, 278 
waiting for input, 291 
Program input 
INPUT, 199 
INPUT LINE, 202 
LINPUT, 207 
waiting for, 291 
Program lines 
automatic sequencing, 107 
deleting, 54 
displaying, 75 
editing, 57 
elements of, 1 
format of, 1 to 8 
length of, 1 
numbering, 1 
order of, 8, 98 
resequencing, 98 
terminating, 1, 7, 10 
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Programs 
compiling, 51 
continuing, 53, 103 
debugging, 84, 91, 103 
deleting, 111 
editing, 57 
ending, 162 
executing, 102 
halting, 53, 103, 279 
merging, 43 
naming, 79 
optimizing, 87 
renaming, 95 
saving, 97, 104 
stopping, 53, 103, 279 
Promotion rules 
data type, 31 to 34 
DECIMAL, 32 
floating-point, 31 
integer, 31 
Prompt 
after STOP, 279 
debugger, 381 
INPUT, 199 
INPUT LINE, 202 
LINPUT, 207 
MAT INPUT, 219 
MAT LINPUT, 221 
PSECT, 139, 210 
PUT, 258 to 259 


Q 


Qualifiers, 83 to 94 
abbreviated form, 83 
ANSI_STANDARD, 84 
AUDIT, 84 
BASIC—PLUS—2 command, 90t 
BOUNDS_CHECK, 84 
BRLRES, 90 
BYTE, 84, 90 
CHAIN, 90, 134 
CLUSTER, 90 
CROSS_REFERENCE, 84, 90 
DEBUG, 84, 91, 103, 381 
DECIMAL_SIZE, 84 
DOUBLE, 85, 91 
DSKLIB, 91 
DUMP, 91 
EXTEND, 91 
FLAG, 85, 91 
GFLOAT, 86 
HFLOAT, 86 
IND, 92 
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Qualifiers (Cont.) 
LIBRARY, 92 
LINE, 86, 92, 134, 387, 388 
LIST, 86 
LONG, 87, 92 
MACHINE_CODE, 87 
MACRO, 92 
MAP, 93 
NOLINE, 279 
OBJECT, 87, 93 
ODLRMS, 93 
OVERFLOW, 87 
PAGE_SIZE, 93 
REL, 93 
RMSRES, 93 
ROUND, 87 
SEQ, 93 
SETUP, 87 
SHOW, 88, 120 
SINGLE, 88, 94 
SYNTAX_CHECK, 88, 94 
TRACEBACK, 88 
TYPE_DEFAULT, 89, 94 
VARIANT, 89, 94, 128 
VAX—-11 BASIC command, 84t 
VIR, 94 
WARNINGS, 89 
WIDTH, 94 
WORD, 89, 94 
QUO$, 349 to 350 
rounding and truncation values, 344t 
Quotation marks 
in string literals, 18 


R 


R formatting character 
in PRINT USING, 256 
RAD$, 351 
Radix 
binary, 21 
decimal, 21 
hexadecimal, 21 
in explicit literal notation, 21 
octal, 21 
Radix—50, 351 
Random numbers, 260, 357 
RANDOMIZE, 260 
See also RND 
Range 
of data types, 12 
of subscripts, 28 
RCTRLC, 352 
See also CTRLC 
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RCTRLO, 353 
READ, 261 to 262 
See also DATA 
with DATA, 143, 144 
with NOSETUP, 88 
REAL data type, 11 
REAL function, 354 
Receiving parameters 
FUNCTION subprograms, 184 
SUB subprograms, 281 
Record attributes 
MAP clause, 243 
RECORDSIZE clause, 242, 243 
RECORDTYPE clause, 241 
Record buffers 
DATA pointers, 271 
MAP DYNAMIC pointers, 214, 269 
moving data, 227 
REMAP pointers, 268, 269 
setting size, 243 
RECORD clause, 172, 190, 258, 259 
Record File Address, 12, 172, 190, 321 
Record Management Services, 80 
See also RMS 
Record pointers 
after FIND, 173, 174 
after GET, 191, 192 
after PUT, 259 
after UPDATE, 289 
REMAP, 269 
RESTORE, 271 
WINDOWSIZE clause, 242 
RECORD statement, 263 to 266 
Records 
deleting with DELETE, 157 
_ deleting with SCRATCH, 275 
finding RFA of, 172, 190 
locating randomly, 174 
locating sequentially, 173 
locating with FIND, 171 
locking, 173, 174, 191, 192, 245 
processing of, 245 
retrieving by KEY, 190, 192 
retrieving by RECORD number, 190 
retrieving by RFA, 190, 192 
retrieving randomly, 192 
retrieving sequentially, 190, 191 
retrieving with GET, 189 
size of, 258 
unlocking, 157, 174, 182, 192, 245, 
writing with PRINT, 251 
writing with PUT, 258 
writing with UPDATE, 289 
RECORDSIZE clause, 212, 242, 258 


287 
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RECORDTYPE clause 
ANY, 241 
FORTRAN, 241 
LIST, 241 
NONE, 241 
RECOUNT debugger command, 396 
RECOUNT function, 355 
after GET, 192 
after INPUT, 200 
after INPUT LINE, 203 
after LINPUT, 208 
Recursion 
in DEF functions, 151 
in DEF™ functions, 155 
in error handlers, 234 
in subprograms, 132, 282 
Redimensioning arrays 
dynamic, 160 
with executable DIM, 159 
with MAT statements, 217, 218, 219, 221, 
225 
REDIRECT debugger command, 397 
Referencing labels, 2 
REGARDLESS clause 
with FIND, 174 
with GET, 192 
REL qualifier, 93 
Relational expressions, 35 to 37 
compared with logical, 40 
definition of, 34 
format of, 35 
in SELECT, 276, 277 
numeric, 35 
string, 36 
truth tests, 35, 36 
Relational operators 
numeric, 35t 
string, 37t 
Relative files 
BUCKETSIZE clause, 244 
deleting records in, 157 
finding records in, 173 
opening, 240 
record size in, 242 
REL qualifier, 93 
retrieving records sequentially in, 191 
updating, 290 
writing records to, 258 
REM, 267 
in multi-statement lines, 7 
multi-line format, 9, 267 
transferring control to, 9 
REMAP, 268 to 270 
FILL item formats and storage, 141t 


Index—20 


REMAP (Cont.) 
with MAP DYNAMIC, 214 
with NOSETUP, 88 
RENAME, 95 to 96 
Renaming 
files, 230 
programs, 95 
REPLACE, 97 
with RENAME, 95 
RESEQUENCE, 98 to 99 
Reserved words, 3 
RESET, 271 
See also RESTORE 
RESTORE, 271 
Restoring 
data, 271 
files, 271 
Result data types 
for DECIMAL data, 33t 
GFLOAT and HFLOAT, 32t 
mixed-mode expressions, 32t 
RESUME, 272 
after CTRL/C, 272 
to INPUT, 200 
to INPUT LINE, 203 
to LINPUT, 208 
with CTRLC, 362 
with END, 162 
with ERL, 312 
with ERN$, 313 
with ERR, 314 
with labels, 2 
with NOLINE qualifier, 86, 92 
with NOSETUP, 88 
Retrieving records 
randomly by KEY, 190, 192 
randomly by RECORD number, 190 
randomly by RFA, 190, 192 
sequentially, 190, 191 
with GET, 189 
RETURN, 273 
RFA clause, 172, 190 
RFA data type 
allowable operations, 12 
storage of, 12 
RIGHT$, 356 
See also SEG$ 
Right-justification 
PRINT USING format field, 256 
with RSET, 274 
RMS 
files, 238 
libraries, 93, 100, 101t 
ODL files, 80, 81t 
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RMSRES command, 100 to 101 Sequential files (Cont.) 


BUILD default, 48 retrieving records in, 191 
RMSRES qualifier, 93 SEQ qualifier, 93 
RND, 357 updating, 289 

See aiso RANDOMIZE writing records to, 251, 258 
ROUND qualifier, 87 SET, 108 
Rounding BASIC—PLUS—2 qualifiers, 90t 

controlling with OPTION, 249 BUILD default, 48 

controlling with SCALE, 105 qualifier format, 83 

DECIMAL values, 87, 249 VAX—11 BASIC qualifiers, 84t 

in numeric strings, 342, 344t, 347, 349 Setting defaults 

NUM$, 339 for data types, 13 

with PRINT, 252 with BRLRES, 46 

with PRINT USING, 255 with DSKLIB, 55 
RSET, 274 with LIBRARY, 73 
RSTS/E SYS calls, 369 with ODLRMS, 80 
RUN, 102 to 103 with OPTION, 248 

BASIC—PLUS—2 qualifiers, 90t with RMSRES, 100 

DEBUG qualifier, 381 with SCALE, 105 
Run-Time Library, 87 with SET, 108 
RUNNH, 102 SETUP qualifier, 87 

See also RUN SGN, 359 

SHOW, 109 to 110 
S SHOW qualifier 
CDD_DEFINITIONS, 88, 120 
SAVE, 104 ENVIRONMENT, 88 

with RENAME, 95 INCLUDE, 88, 120 
Saving programs MAP, 88 

with REPLACE, 97 OVERRIDE, 88 

with SAVE, 104 SI, 24 
%SBTTL, 126 SIN, 360 
SCALE, 105 Sine, 360 
Scale factor SINGLE data type, 11 

setting with OPTION, 249 SINGLE qualifier, 88, 94 

setting with SCALE, 105 Single-line 
SCRATCH, 106, 275 DEF, 149 
SEG$, 358 DEF*, 153 
Segmented keys, 244 loops, 179, 288, 292 
SELECT, 276 to 277 statements, 4 

transferring control into, 236, 237 Single-statement lines, 4 
Semicolon (;) Size 

in INPUT, 199 of numeric data, 12 

in INPUT LINE, 202 of STRING data, 11 

in LINPUT, 207 SLEEP, 278 

in MAT PRINT, 224 SO, 24 

in PRINT, 251 SP, 24 
SEQ qualifier, 93 SPACE$, 361 
SEQUENCE, 107 Spacing in keywords, 4 
Sequential files SQR, 362 

deleting records in, 275 ; SQRT, 362 

finding records in, 173 Square roots, 362 

NOSPAN clause, 243 Statement modifiers 

opening, 240 FOR, 179 

record size in, 242 IF, 197, 198 
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Statement modifiers (Cont.) 
UNLESS, 286 
UNTIL, 288 
WHILE, 292 
Statements 
backslash separator, 5 
block, 162, 164, 179, 197, 264, 277 
BP2 compatible, 85 
components of, 3 
continued, 4, 5 
data typing, 14 
declarative, 145 
declining, 85, 91 
empty, 10 
executable, 3 
execution of, 5 
format of, 3 
labelling of, 2 
multi-statement lines, 5 to 7 
nonexecutable, 3, 8, 141, 143, 147, 159, 
168, 211, 214, 267 
order of, 8, 98 
processing of, 8 
single-line, 4 
Static 
arrays, 158, 159 
mapping, 210 
storage, 139, 210, 269 
STATUS debugger command, 398 to 399 
STATUS function, 363 to 364 
VAX—11 BASIC STATUS bits, 364t 
STEP clause, 179 
STEP debugger command, 400 
STOP, 279 
See also CONTINUE command 
with RUN, 103 
Stopping program execution, 53, 279, 383, 
400 
Storage 
allocating with REMAP, 268 
COMMON and MAP, 141, 211 
dynamic, 213, 268, 269 
for arrays, 159 
for FILL items, 141t, 227, 268 
for RECORD structures, 264 
for VARIANT fields, 265 
in COMMON, 142 
in MAP, 211 
of data, 12 
of DECIMAL data, 11 
of RFA data, 12 
of STRING data, 11 
shared, 139, 210 
static, 139, 210, 269 
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STR$, 365 
String arithmetic functions 
DIF$, 309 
PLACE$, 342 
PROD$, 347 
QUO$, 349 
SUM$, 367 
String constants, 18 to 19 
STRING data type, 11 
length, 12 
storage of, 11 
STRING debugger command, 401 
String expressions, 34 
relational, 36, 37 
String functions, 304 
ASCH, 295 
EDIT$, 311 
INSTR, 322 
LEFT$, 326 
LEN, 327 
MID$, 335 
POS, 345 
RIGHT$, 356 
SEG$, 358 
SPACE$, 361 
STRING$, 366 
TRM$, 376 
with NOSETUP, 87 
XLATE, 379 
String literals, 37 
continuing, 5 
delimiter, 18 
in PRINT USING format fieid, 257 
processing of, 10 
quotations marks in, 18 
String relational expressions 
evaluation of, 36 
operators, 37t, 37 
String variables, 27 
formatting storage, 209, 274 
in INPUT, 200 
in INPUT LINE, 203 
in LET, 206 
in LINPUT, 208 
with NOSETUP, 87 
STRING$, 366 
Strings 
comparing, 36, 300 
concatenating, 5, 30, 34, 88 
~ converting, 136 
creating, 361, 366 
editing, 311, 376 
extracting substrings, 326, 335, 356, 358 
finding length, 327 
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trings (Cont.) 
finding substrings, 322, 345 
justifying with FORMATS, 318 
justifying with LSET, 209 
justifying with PRINT USING, 256 
justifying with RSET, 274 


numeric, 300, 309, 325, 342, 347, 349, 


354, 367, 377, 378 
suffix character, 13 
SUB, 280 to 283 
BASIC—PLUS—2 parameter passing 
mechanisms, 133t 
parameters, 281 
VAX—11 BASIC parameter passing 
mechanisms, 132t 
SUBEND, 284 
See also END 
SUBEXIT, 285 
See also EXIT 
Subprograms 
calling, 129 
declaring, 166 
ending, 162, 184, 281 
error handling in, 163, 164, 185, 233 
exiting, 164 
FUNCTION, 183 
naming, 130, 281 
recursion in, 132, 282 
returning from, 273 
SUB, 280 
Subroutines 
external, 166 
GOSUB, 195 
RETURN, 273 
Subscripted variables, 27 to 29 
format of, 28 
range checking, 84, 249 
subscript range, 28 
Subscripts, 27 
range of, 28 
SUBSTITUTE editing command, 66 to 67 
Substrings 
extracting, 326, 335, 356, 358 
finding, 322, 345 
Suffix characters 
integer, 13 
string, 13 
SUM$, 367 
Suspending program execution, 278 
SWAP%, 368 
SYNTAX_CHECK qualifier, 88, 94 
SYS, 369 to 370 
VAX-11 BASIC subset, 369t 
System command, 49 
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TAB, 371 
TAN, 372 


-heront 


Tangent, B72 

Template, 264 
TEMPORARY clause, 242 
Tensor, 28 

Terminal 


printing to, 251 


Terminal control functions 


ECHO, 310 
NOECHO, 336 
RCTRLO, 353 
TAB, 371 


Terminal-format files, 244 
input from, 199, 202, 207, 219, 221 


margin, 215, 232 
writing records to, 223, 251 


Terminating 


automatic sequencing, 107 
comment fields, 8 
compilation, 113 

DATA statements, 143 
program lines, 1, 7, 10 
REM statements, 9, 267 


THEN clause, 197 
TIME, 373 to 374 


function values, 374t 


TIME$, 375 

%TITLE, 127 

TRACE debugger command, 402 
TRACEBACK qualifier, 88 


Trailing minus sign field 
n PRINT USING format field, 255 


iM rime U iitiaet tt ; 


Transferring control 
into DEF functions, 151, 236, 237 


into DEF* functions, 155 


into FOR-NEXT loops, 180, 195, 196, 236, 


237 
into SELECT blocks, 236, 237 


into UNTIL loops, 195, 196, 236, 237 
into WHILE loops, 195, 196, 236, 237 


to a label, 195, 196, 236, 237 
to comment fields, 8 

to multi-statement lines, 5 

to REM, 9 

with CALL, 129 


‘with CHAIN, 134 


with GOSUB, 195 
with GOTO, 196 

with IF, 197 

with ON-GOSUB, 236 
with ON-—GOTO, 237 
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Transferring control (Cont.) 
with RESUME, 203, 208, 272 
with RETURN, 273 

Transferring data 
with MOVE, 227 

Translating character sets 

Transposing arrays, 218 

Trigonometric functions 
AIN, 296 
COS, 301 
SIN, 360 
TAN, 372 

TRM$, 376 

TRN, 218 

Truncation 
in numeric strings, 342, 344t, 347, 349 
in PRINT USING, 256 
with FIX, 317 

Truth tables, 38t 

Truth tests 
in logical expressions, 38 
in relational expressions, 35 
in string relational expressions, 36 

TYPE_DEFAULT qualifier, 89, 94 


U 


, 379 


UNBREAK debugger command, 403 to 404 
Unconditional branching 
with GOSUB, 195 
with GOTO, 196 
Unconditional loops, 179 
Underscore (_) 
in PRINT USING format field, 255 
in variable names, 25 
UNLESS, 286 
UNLOCK, 287 
UNLOCK EXPLICIT clause, 173, 175, 191, 
245 
Unlocking records, 245 
with FREE, 182 
with UNLOCK, 287 
UNSAVE, 111 
UNTIL clause, 180 
UNTIL loops, 231 
error handling in, 272 
exiting, 164 
explicit iteration of, 204 
transferring control into, 195, 196, 236, 237 
UNTIL statement, 288 
UNTRACE debugger command, 405 
UPDATE, 289 to 290 
with UNLOCK, 287 
Updating records, 289 
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Uppercase letters 
in EDIT, 58 
in FIND editing command, 64 
in PRINT USING, 256 
in SUBSTITUTE editing command, 66 
processing of, 10 
User-defined functions, 149, 153 
USEROPEN clause, 240, 243 


V 


VAL, 377 
VAL%, 378 
Variable names 
in COMMON, 142 
in MAP, 211, 212 
in MAP DYNAMIC, 213 
in REMAP, 268 
rules for, 25 to 26 
Variables, 25 to 29 
assigning values to, 199, 202, 206, 207, 
261, 393 
declaring, 145 
definition of, 25 
explicitly declared, 27 
external, 166 
floating-point, 26 
implicitly declared, 26 to 27 
in MOVE, 228 
in SUB subprograms, 282 
initialization of, 29, 142, 147, 212 
integer, 27 
ioop, 179 
naming, 25 to 26 
string, 27, 200, 203, 206, 208 
subscripted, 27 to 29 
%VARIANT, 128 
in %IF, 117 
in %LET, 121 
Variant, 264 
VARIANT clause, 264 
VARIANT qualifier, 89, 94, 128 
VAX-—11 BASIC STATUS bits, 364t 
VAX—11 BASIC subset of RSTS/E SYS calls, 
369t 
Vector, 28 
Version identification, 115 
VIR qualifier, 94 
Virtual address 
finding, 328 
Virtual arrays, 147, 158, 159 
initialization of, 29, 160 
padding in, 160 
with FIELD, 170 
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Virtua! arrays (Cont.) WORD data type,-11 


with NOSETUP, 88 WORD qualifier, 89, 94 
Virtual files Writing records 

record size, 242 by RECORD number, 258 

VIR qualifier, 94 sequentially, 258 

with RESTORE, 271 with PRINT, 251 
VT, 24 with PUT, 258 

with UPDATE, 289 
WwW 
X 

WAIT, 291 
WARNINGS qualifier, 89 XLATE, 379 
WHILE clause, 180 XOR, 38 
WHILE loops, 231 

error handling in, 272 Zz 

exiting, 164 

explicit iteration of, 204 ZER, 217 

transferring control into, 195, 196, 236, 237 Zero 
WHILE statement, 292 array element, 28, 159, 218, 220, 222, 224, 
Width 226, 228 

margin, 215, 232, 251, 334 blank-if-zero field, 255 

of listing file, 94 in PRINT USING format field, 255 
WIDTH qualifier, 94 Zero-fill field 
WINDOWSIZE clause, 242 in PRINT USING, 255 
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